killport

List and kill the process listening on a TCP port. macOS + Linux, zero deps.

An interactive TUI replacement for lsof -i:3000 && kill -9 <pid>. Pick a listener with the arrow keys, hit Enter, get a graceful kill (SIGTERM, then SIGKILL after 3 seconds if it's still alive).

Install

git clone <repo> ~/code/killport
cd ~/code/killport
npm link              # creates a global symlink
killport              # works

No dependencies. Requires Node 20+.

Usage

killport                interactive TUI (default; needs a TTY)
killport --no-tui       numbered list + readline prompt (works piped / over SSH)
killport --port <n>     kill whatever is on port <n>, non-interactive
killport --list         print the list and exit
killport --help
killport --version

Keys (TUI)

| Key | Action | | -------------- | --------------------------------------------------- | | ↑ / ↓ | move | | PgUp / PgDn| page | | Home / End | first / last | | Enter | kill highlighted (SIGTERM → 3s → SIGKILL) | | r | refresh | | q / Ctrl-C | quit |

Examples

killport --port 3000          # script-friendly: kill whatever is on :3000
killport --no-tui | head -20   # list first 20 listeners, non-interactive
sudo killport --port 80        # privileged listener (the tool will suggest sudo on EPERM)

How it works

• macOS — one lsof -nP -iTCP -sTCP:LISTEN -F pcn0tTu call, parses the field output (NUL-separated). User names are resolved from /etc/passwd first, falling back to id -un <uid> (handles normal users in OpenDirectory that aren't in /etc/passwd).
• Linux — reads /proc/net/tcp + /proc/net/tcp6 to find LISTEN sockets and their inodes, then walks /proc/<pid>/fd to map each socket back to its owning PID. No external binaries required.

The kill flow sends SIGTERM, polls every 200ms (signal 0) up to 3s, and escalates to SIGKILL if the process is still alive. Permission errors (EPERM/EACCES) are reported inline with a hint to use sudo — the tool never escalates on its own.

Platforms

• macOS (primary) — tested on darwin
• Linux — /proc-based; should work on any modern kernel
• Windows — not supported

Limitations

• TCP only. UDP listeners are out of scope.
• Doesn't track child processes — if the listener spawned workers, only the listening parent is killed.
• If a port is bound by multiple PIDs (rare but possible), the TUI shows one row per pid:port pair. --port <n> in non-interactive mode will kill all matching PIDs.

Distribution

Local via npm link. When npm publish is set up, the Homebrew formula will be a tarball install pointing at the npm registry.

License

MIT