portvac

See what's listening on a TCP port - and free it. The "port already in use" error costs every developer a minute of lsof / netstat / taskkill archaeology. portvac lists who's on a port in one command, then vacates it on confirm. Cross-platform, zero dependencies.

npx portvac            # list every listening TCP port
npx portvac 3000       # show what's on 3000, then kill it (asks first)
npx portvac 3000 -k    # kill without asking (scripts / CI)
npx portvac 3000 -s KILL   # SIGKILL instead of the default SIGTERM

Python shop?

pip install portvac
portvac 3000 -k

Why

"Port 3000 is already in use" - and now you're pasting lsof -i :3000 into Stack Overflow for the fourth time this week.

lsof flags differ from netstat which differs from Windows taskkill. You remember none of them under pressure. portvac is the one command that works the same on macOS, Linux, and Windows: look first, kill second, never silent.

How it works

1. List - shells out to the platform's own tool (lsof / ss / netstat) to read listening sockets. No daemon, no network.
2. Show - prints a clean table: port, pid, process name, address, family.
3. Vacate - on a port argument, asks y/N, then sends a signal (default TERM) to the owning pid(s). -k skips the prompt.

Nothing is installed system-wide and no data leaves your machine.

Usage

portvac                       List every TCP port currently listening
portvac <port>                Show what's on <port>, then kill it (asks first)
portvac <port> --list         Show only, don't kill
portvac <port> -k             Kill without confirmation
portvac <port> -s KILL        Send KILL instead of TERM
portvac --json [<port>]       Machine-readable output (great for piping)

  -k, --force         Kill without confirmation
  -l, --list          List only; never kill
  -s, --signal <SIG>  TERM (default), KILL, INT, QUIT, HUP
      --json          Emit JSON; suppresses colors and prompts
  -v, --version

JSON

$ portvac --json 3000
{
  "port": 3000,
  "listeners": [
    { "port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4" }
  ]
}

Platform notes

| Platform | Lookup | Kill | |----------|--------|------| | macOS / BSD | lsof -iTCP -sTCP:LISTEN -P -n | process.kill(pid, SIG) | | Linux | ss -tlnp (falls back to netstat -tlnp) | os.kill(pid, sig) | | Windows | netstat -ano + tasklist | taskkill /PID <pid> /F /T |

On Windows there's no POSIX signal hierarchy, so portvac force-terminates (taskkill /F). To see another user's processes you may need elevated privileges, same as the underlying tools.

Exit codes

| Code | Meaning | |------|---------| | 0 | listed, or killed successfully | | 1 | nothing listening / port not in use / aborted | | 2 | error (bad args, tool missing, kill failed) |

License

MIT