Port-nuker 🔥

A simple CLI utility to kill processes holding a specific port. Solves the EADDRINUSE error instantly.

Installation

Global Installation (Recommended)

Install globally via npm:

npm install -g port-nuker

Or use with npx (no installation required):

npx port-nuker 3000

Local Development

1. Clone this repository
2. Run npm link in the project directory

Usage

# Auto-detect port from package.json (no arguments needed!)
nuke

# Kill process on specific port
nuke <PORT>

# Kill and wait until port is actually free
nuke <PORT> --wait

# Force kill even on protected ports
nuke <PORT> --force

# Kill entire process group (parent + all children)
nuke <PORT> --deep

# Kill processes on a port range
nuke <START>-<END>

# Kill processes on multiple specific ports
nuke <PORT1>,<PORT2>,<PORT3>

# List all active ports and select one to kill interactively
nuke list

Examples

Smart Detection

# 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!

Basic Usage

Direct Port Killing:

# 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:

# 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):

# 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

Development Server Already Running

# Error: EADDRINUSE: address already in use :::3000
nuke 3000
npm run dev

Port Conflict After Crash

# Your app crashed but the port is still held
nuke 8080
node server.js

Protected Ports (Safe Mode)

# 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)

Docker Containers

# 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

Microservices Stack

# 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)

Zombie Processes

# 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.

License

MIT © [Your Name]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you encounter any problems, please open an issue.