Your cross-platform port detective — find, inspect, and kill processes by port number or process name.

No dependencies. Works on macOS, Linux, and Windows.

Every fullstack developer has googled lsof -i :3000 at least once a week. portcop makes it one clean command that works everywhere — no memorizing OS-specific flags, no piping through grep, no copy-pasting PIDs.

npm install -g portcop

portcop 3000

  Checking port 3000...

  ✘ Port 3000 is occupied

    Process : node
    PID     : 8421
    Command : node server.js

  Kill it? (y/n)

portcop 3000 --kill

  ✔ Killed node (PID 8421)

portcop 3000 4000 5000

  ✘ Port 3000 → node  PID 8421  node server.js
  ✔ Port 4000 is free
  ✘ Port 5000 → python  PID 9103  python app.py

  Kill all 2 occupied? (y/n)

portcop ls

  Scanning all occupied ports...

  3000  node            PID 8421    node server.js
  5173  node            PID 9103    node vite.js
  8080  python          PID 9210    python manage.py runserver

  3 ports occupied

portcop -n node

  Searching for processes matching "node"...

  Found 3 processes matching "node"

  ✘ Port 3000  node  PID 8421
     node server.js
  ✘ Port 5173  node  PID 9103
     node vite.js
  ✘ Port 8080  node  PID 9210
     node webpack.js

  Kill all 3?  y / n / ports (e.g. 3000,5173,8080)

At the prompt you can:

• y — kill all matching processes
• n — cancel, no action taken
• 3000 — kill a single port only
• 3000,5173 — kill specific ports, leave the rest running

portcop -n node --kill

  ✔ Killed node (PID 8421)
  ✔ Killed node (PID 9103)
  ✔ Killed node (PID 9210)

portcop free 3000

  ✔ Port 3000 is free

portcop free 3000-3010

  Scanning ports 3000–3010...
  ✔ First free port: 3003

portcop free 3000+ --count 5

  Finding 5 free ports from 3000...
  ✔ 3000
  ✔ 3001
  ✔ 3003
  ✔ 3005
  ✔ 3006

macOS: uses lsof

Linux: tries 3 strategies in order, using the first one that works:

1. lsof — available on most distros
2. ss — modern replacement for netstat, used when lsof isn't installed
3. /proc/net/tcp — pure Linux kernel file, no tools needed at all. Works in Docker containers, CI runners, and minimal environments where nothing is installed

Windows: chains netstat -ano → tasklist (no single command gives port + process name together)

All OS differences are abstracted away. The CLI output is identical everywhere.

Note: On some systems, killing processes on privileged ports (< 1024) may require sudo.

node test.js

The test suite spins up real TCP servers to verify behavior end-to-end, with zero test framework dependencies.

MIT