kill-port-cli

Find and kill processes using a specific port. Zero dependencies. Works on Windows, macOS, and Linux.

"Port 3000 is already in use" — the most annoying error in web development. Fixed in one command.

Why?

Every developer hits this: you kill a dev server, but the port stays occupied. Maybe a zombie Node process, maybe a forgotten Docker container. You Google "how to kill process on port", copy-paste a 3-line bash command... and on Windows it's completely different.

kill-port-cli gives you one command that works everywhere:

npx kill-port-cli 3000
# ✔ Killed PID 12345 on port 3000

No lsof | grep | awk | xargs kill. No netstat -ano | findstr. Just the port number.

Install

npm i -g kill-port-cli

Or run directly without installing:

npx kill-port-cli 3000

Usage

Kill a single port

kill-port-cli 3000
# ✔ Killed PID 12345 on port 3000

Kill multiple ports at once

kill-port-cli 3000 8080 5432
# ✔ Killed PID 12345 on port 3000
# ✔ Killed PID 23456 on port 8080
# ✔ Killed PID 34567 on port 5432

List all listening ports

kill-port-cli --list
# PORT   PID    PROCESS
# 3000   12345  node
# 5432   23456  postgres
# 8080   34567  java

Common workflows

# Free up your dev server port before starting
kill-port-cli 3000 && npm run dev

# Clean up after a crashed Docker compose
kill-port-cli 3000 5432 6379

# Find what's using port 80
kill-port-cli --list | grep 80

# Use in npm scripts
# package.json: "predev": "npx kill-port-cli 3000"

Options

Argument	Description
<port> [port...]	Kill processes on the given port(s)
--list, -l	List all listening ports and their PIDs
--help, -h	Show help

Use Cases

• Web development — Free port 3000/8080 when your dev server crashes
• Database work — Kill a stuck Postgres or Redis process hogging a port
• CI/CD pipelines — Ensure ports are free before integration tests
• Docker cleanup — Kill orphaned containers still binding ports
• npm scripts — Add as a predev or pretest script for reliable port availability

How it works

Platform	Method
macOS / Linux	lsof -i :<port> to find PID, then kill -9
Windows	netstat -ano to find PID, then taskkill /F /PID

No child_process chains. No shell piping. Just Node's built-in child_process.execSync with proper cross-platform handling.

Comparison

Tool	Zero deps	Cross-platform	Multiple ports	List ports	Install
kill-port-cli	✅	✅ Win/Mac/Linux	✅	✅	npx kill-port-cli
kill-port	❌ (2 deps)	✅	❌ (one at a time)	❌	npx kill-port
fkill-cli	❌ (15+ deps)	✅	✅	❌	npx fkill-cli
lsof + kill	N/A	❌ Unix only	Manual	Manual	Built-in (Unix)
netstat + taskkill	N/A	❌ Windows only	Manual	Manual	Built-in (Win)

Related

• find-open-port-cli — Find an available port
• env-lint-cli — Lint .env files against .env.example

License

MIT © 2026 kszongic