whoisport

Find out what is listening on a port, who started it, and stop it safely. Works on Linux, macOS and Windows. One small binary, no runtime dependencies.

lsof -i :3000 gives you a PID and a wall of columns. whoisport gives you the command line, the directory it was started from, who owns it and how long it has been running, which is usually what you need to decide whether to kill it. And when you do kill it, whoisport makes sure it only stops the process you were looking at.

Quickstart

whoisport              # what is listening on this machine?
whoisport 3000         # what is on port 3000, and who started it?
whoisport 3000 --kill  # ask it to exit (add --force if it refuses)

$ whoisport 3000
port    3000
pid     373232
parent  373230
user    kaitlyn
cmd     node node_modules/.bin/vite --port 3000
cwd     /home/kaitlyn/site
uptime  4m 12s

$ whoisport 3000 --kill
...
pid 373232: exited after SIGTERM

$ whoisport
PORT   PID      USER       CMD
3000   373232   kaitlyn    node node_modules/.bin/vite --port 3000
5432   ?        ?          ?
8080   41120    kaitlyn    python3 -m http.server 8080
ports marked ? are owned by another user; run with sudo to see it

Install

Or download a binary from the Releases page: Linux (static, x86_64 and aarch64), macOS (Apple silicon and Intel) and Windows (x86_64).

Supported systems: Linux (reads /proc, no other tools needed), macOS (uses the built-in lsof), Windows 10 and 11.

Usage

whoisport [PORTS]... [--kill [--force]] [--json] [--udp]

--kill always needs explicit ports; it never means "kill everything". --json cannot be combined with --kill.

JSON output

--json prints an array with one object per listener. Every object has the same keys; what is unknown (for example the owner of a process you may not inspect) is null:

[
  {
    "port": 3000, "proto": "tcp", "pid": 373232, "ppid": 373230, "user": "kaitlyn",
    "cmd": "node node_modules/.bin/vite --port 3000", "cwd": "/home/kaitlyn/site",
    "uptime_secs": 252, "container": null, "image": null
  }
]

Exit codes

Reading ?

On Linux, a process owned by another user cannot be inspected without sudo, so its row shows ?. On macOS lsof only lists your own processes without sudo, so other users' listeners are missing. On Windows, details of system services need an elevated terminal.

Stopping processes safely

--kill is built so that it cannot take down more than you meant to:

• The process you saw is the process that is signalled. Each target is identified by its pid and its start time. If it exits and the system hands its pid to something else, that something else is left alone.
• Service managers and parents are never signalled. When several processes share a socket (a supervisor and its workers, or systemd socket activation), stopping the supervisor takes down far more than one port. systemd, launchd and svchost.exe, and any process that is a parent of another holder, are skipped. whoisport then says which one still holds the port and exits 3.
• It asks first. Each target is asked to exit; it is forced only with --force.

On Windows, Ctrl+C reaches every program attached to a console, so whoisport only sends it when the target's console holds nothing but the target, its child processes and a shell. Otherwise it says so and leaves the choice of --force to you.

Text from other processes (command lines, paths) is printed with control characters, bidirectional-text overrides and zero-width characters escaped, so a hostile process cannot rewrite your terminal or disguise what it is.

Docker

When a port is published by a container, whoisport shows the container name and image (docker web (nginx:alpine)), even though the docker-proxy process behind it is owned by root. Docker is consulted only when a listener looks like Docker's forwarder or its owner cannot be read, only for a local daemon (not an ssh:// or remote DOCKER_HOST), and each Docker call is cut off after 2 seconds, so a stuck daemon never hangs whoisport: the names are simply left out. --kill on such a port prints the matching docker stop <name> command, because killing the forwarder only breaks the port mapping.

UDP

UDP has no listening state, so --udp lists bound sockets that have no remote peer. Windows does not report UDP peers, so there every bound UDP socket is listed, including short-lived client ones.

How it works

A short version (the long one is in ARCHITECTURE.md): whoisport asks the operating system which sockets are listening and which process owns each one, looks up details of those processes, and prints them. Each platform has its own small backend for that (/proc on Linux, lsof on macOS, the IP Helper API on Windows); everything else is shared.

cli ─► scan ─► output     (list, details, JSON)
         │
         └───► kill       (identity, safety rules, ask-then-force)
         ▲
   proc backend per OS · docker names

Development

cargo test                 # unit and end-to-end tests
cargo clippy --all-targets -- -D warnings

See CONTRIBUTING.md for the full workflow (formatting, coverage, checking the other platforms, commit style) and ARCHITECTURE.md for how the code is organised.

License

MIT