A simple CLI utility to kill processes holding a specific port. Solves EADDRINUSE errors instantly.
npm install port-nukerEADDRINUSE error instantly.
bash
npm install -g port-nuker
`
Or use with npx (no installation required):
`bash
npx port-nuker 3000
`
$3
1. Clone this repository
2. Run npm link in the project directory
Usage
`bash
Auto-detect port from package.json (no arguments needed!)
nuke
Kill process on specific port
nuke
Kill and wait until port is actually free
nuke --wait
Force kill even on protected ports
nuke --force
Kill entire process group (parent + all children)
nuke --deep
Kill processes on a port range
nuke -
Kill processes on multiple specific ports
nuke ,,
List all active ports and select one to kill interactively
nuke list
`
$3
$3
`bash
Just run 'nuke' in your project directory
cd my-next-app
nuke
Output:
📦 Detected project port from package.json: 3000
Kill process on port 3000? (Y/n): y
#
Searching for process holding port 3000...
Found process with PID: 12345. Nuking it...
Successfully nuked process 12345.
Works with multiple ports detected
nuke
Output:
📦 Detected multiple ports from package.json: 3000, 4000, 5000
Which port would you like to kill?
❯ Port 3000
Port 4000
Port 5000
Cancel
Supports common frameworks:
- Next.js: "next dev -p 3000"
- Vite: "vite --port 4000"
- Express: "PORT=5000 node server.js"
- And more!
`
$3
Direct Port Killing:
`bash
Kill process on port 3000
nuke 3000
Kill process on port 8080
nuke 8080
Using npx (without global install)
npx port-nuker 3000
`
Interactive Port Selection:
`bash
List all active ports with details
nuke list
You'll see a table like this:
┌──────┬──────────┬──────────┬──────────────────────────────┬───────────────┬────────────┐
│ Port │ PID │ Protocol │ Command │ User │ Memory │
├──────┼──────────┼──────────┼──────────────────────────────┼───────────────┼────────────┤
│ 3000 │ 12345 │ TCP │ node.exe │ username │ 45,232 K │
│ 8080 │ 67890 │ TCP │ java.exe │ username │ 128,456 K │
└──────┴──────────┴──────────┴──────────────────────────────┴───────────────┴────────────┘
#
Use arrow keys to select a process and press Enter to kill it
`
Wait Mode (Command Chaining):
`bash
Kill and wait for port to be released (polls every 500ms)
nuke 3000 --wait
Chain commands - start dev server only after port is free
nuke 3000 --wait && npm run dev
Works with stubborn processes that take time to release sockets
nuke 8080 --wait && docker-compose up
Timeout after 30 seconds if port isn't released
nuke 5000 --wait && echo "Port is free!"
`
Features
- Cross-Platform: Works on Windows (using netstat + taskkill) and Unix-like systems (Linux/macOS using lsof + kill)
- Smart Project Detection: Auto-detects ports from package.json scripts when run without arguments
- Multi-Kill Support: Kill multiple ports at once using ranges (3000-3005) or comma-separated lists (3000,8080,5000)
- Deep Kill: Kill entire process groups with --deep flag to eliminate zombie child processes
- Docker Awareness: Detects when a port is held by Docker and offers to stop the specific container instead of killing the entire Docker daemon
- Safe Mode Protection: Protected ports (22, 80, 443, 3306, 5432, 6379, 27017, 5000, 8080) require --force flag to prevent accidental termination of critical services
- Interactive Mode: Browse all active ports with nuke list and select which one to kill
- Wait Mode: Block until port is actually released with --wait flag for safe command chaining
- Detailed Process Info: See PID, command name, user, memory usage, and protocol for each port
- Fast: Instantly frees up your port
- Safe: Confirmation prompt before killing processes in interactive mode
- Exact Port Matching: nuke 80 won't kill processes on 8080
- Simple: Just one command to remember
Common Use Cases
$3
`bash
Error: EADDRINUSE: address already in use :::3000
nuke 3000
npm run dev
`
$3
`bash
Your app crashed but the port is still held
nuke 8080
node server.js
`
$3
`bash
Attempting to kill a protected port (e.g., SSH on 22)
nuke 22
Output:
⚠️ Port 22 is protected (SSH).
This port is typically used for critical services.
Use --force to override: nuke 22 --force
Force kill a protected port
nuke 443 --force
Successfully nukes the process on port 443 (HTTPS)
Protected ports: 22 (SSH), 80 (HTTP), 443 (HTTPS), 3306 (MySQL),
5432 (PostgreSQL), 6379 (Redis), 27017 (MongoDB),
5000 (Flask/Docker), 8080 (Alt HTTP)
`
$3
`bash
When a port is held by Docker, port-nuker detects it automatically
nuke 3000
Output:
🐳 Detected Docker process (PID: 12345)
Searching for container using this port...
#
📦 Found container using port 3000:
Name: my-app
ID: abc123def456
Ports: 0.0.0.0:3000->3000/tcp
#
What would you like to do?
1. Stop container 'my-app' (recommended)
2. ⚠️ Kill Docker daemon (stops ALL containers)
3. Cancel
Selecting option 1 stops only the specific container
✅ Successfully stopped container abc123def456
`
$3
`bash
Kill all services in a port range (e.g., microservices on 3000-3005)
nuke 3000-3005
Output:
Killing processes on 6 port(s): 3000, 3001, 3002, 3003, 3004, 3005
#
[1/6] Processing port 3000...
Searching for process holding port 3000...
Found process with PID: 12345. Nuking it...
Successfully nuked process 12345.
#
[2/6] Processing port 3001...
Searching for process holding port 3001...
No process found on port 3001.
#
[3/6] Processing port 3002...
...
#
──────────────────────────────────────────────────
Summary: 4 killed, 2 not found, 0 skipped, 0 failed
Kill specific ports (comma-separated)
nuke 3000,8080,5000
Mixed syntax: ranges and specific ports
nuke 3000-3002,8080,9000-9001
Kills: 3000, 3001, 3002, 8080, 9000, 9001
Works with --force for protected ports
nuke 20-25 --force
Kills ports 20-25 including protected port 22 (SSH)
`
$3
`bash
Scenario: Parent process dies but child processes remain holding the port
Use --deep to kill the entire process group
nuke 3000 --deep
Output:
Searching for process holding port 3000...
Found process with PID: 12345. Nuking it...
#
⚠️ Deep kill mode: Found 4 process(es) in group
PIDs: 12345, 12346, 12347, 12348
#
Nuking process 12345...
Successfully nuked process 12345.
Nuking process 12346...
Successfully nuked process 12346.
Nuking process 12347...
Successfully nuked process 12347.
Nuking process 12348...
Successfully nuked process 12348.
Works with other flags
nuke 3000 --deep --wait
nuke 3000-3005 --deep
nuke 22 --deep --force
`
Requirements
- Node.js >= 12.0.0
How It Works
Windows: Uses netstat -ano to find the PID and taskkill /F to force kill the process.
Linux/macOS: Uses lsof -i to find the PID and kill -9` to terminate the process.