⚡ Portpeek

Find and kill processes occupying ports. Instantly resolve port conflicts.

---

The Problem

You're ready to start your dev server, but... Error: Port 3000 is already in use.

Then you need to:

1. Find the PID (lsof -i :3000 or netstat)
2. Copy the PID
3. Kill it (kill -9 <PID>)
4. Restart your server

Portpeek does this in one command.

Installation

pip install portpeek

Or install from source:

git clone https://github.com/Ak-dude/portpeek.git
cd portpeek
pip install -e .

Quick Start

# Check if a port is in use
portpeek 3000

# Kill whatever's on port 3000
portpeek 3000 --kill

# Force kill (SIGKILL instead of SIGTERM)
portpeek 3000 --kill --force

# List all listening ports
portpeek --list

Examples

Before: The Old Way

$ lsof -i :3000
COMMAND  PID     USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
node    1234   user   20u  IPv4  12345      0t0  TCP *:3000 (LISTEN)

$ kill -9 1234

After: With Portpeek

$ portpeek 3000 --kill
✗ Port 3000 is in use
  PID:     1234
  Process: node
  
Killing 1234... Done!
✓ Port 3000 is now free

Usage

portpeek              # Interactive port browser
portpeek 3000         # Check if port 3000 is in use
portpeek 3000 --kill  # Kill process on port 3000
portpeek --list       # List all listening ports
portpeek 8080 -f      # Force kill port 8080
portpeek --version    # Show version

Why Portpeek?

• ⚡ Fast - One command instead of three
• 🎯 Focused - Does one thing, does it well
• 🔒 Safe - Uses SIGTERM by default (graceful)
• 📦 No deps - Pure Python, no external requirements
• 🖥️ Cross-platform - Works on Linux, macOS (and Windows with WSL)

Requirements

• Python 3.8+
• lsof (Linux/macOS) or netstat/ss (Linux fallback)

License

MIT License - see LICENSE for details.

---

Made with ❤️ by Ak-dude