A fast, interactive terminal UI for scanning ports, identifying what's in use, and reserving free ports for your projects.
Built with Textual — runs entirely in your terminal with no browser required.
- 🔍 Port Scanning: Scans any range of ports (1–65535) to find what's free and what's occupied
- 🖥️ Process Info: Shows the PID and process name for every used port (requires
psutil) - 📦 Range Compression: Free ports are displayed as grouped ranges (e.g.
8080–8095) for easy reading - ⚡ Parallel Scanning: 300-thread concurrent scanning — a full range scan completes in seconds
- 🎯 Smart Recommendations: Suggests the best available ports, with optional contiguous-block preference
- 🚫 Port Exclusions: Exclude specific ports or ranges from results (e.g.
22,80,8000-8010) - 💾 Reservations: Save ports to
~/.portscout/reservations.yamlwith an optional note - ⌨️ Keyboard Driven: Full keyboard control, no mouse required
python portscout.py
The left column shows used ports with their PID and process name.
The right column shows free ports grouped into contiguous ranges.
Press g to open the range dialog and enter your start and end ports.
Press x to exclude specific ports or ranges from the scan. Useful for skipping well-known ports you'll never use.
The bottom panel always shows your best available ports. Press c to switch to contiguous-block mode — useful when your app needs several ports in sequence.
Press v to reserve the top recommended port with an optional note. Saved to disk so you don't forget which port you earmarked for which project.
- Python 3.10+
- pip
pip install -r requirements.txt
requirements.txt:
textual
psutil
pyyaml
psutilis optional but strongly recommended — without it, used ports won't show process names or PIDs.
| Key | Action |
|---|---|
r |
Rescan the current port range |
g |
Change the scan range |
x |
Set port exclusions |
c |
Toggle contiguous-block preference |
v |
Reserve the top recommended port |
h |
Show help |
q |
Quit |
- Default scan range is
1024–9999. You can widen it to1–65535but scans take longer. - Use exclusions to skip ports you know are always occupied on your machine (e.g.
22,5432,6379). - Contiguous mode is handy for apps that need a block of ports in sequence (e.g. a cluster of microservices).
- Reservations are stored in
~/.portscout/reservations.yaml— they're a personal record, not an OS-level lock. - Works on Windows, Linux, and macOS.
PortScout attempts to bind a TCP socket to each port in the range. A successful bind means the port is free; a failure means something is already listening there. All binds run concurrently across a thread pool, so even large ranges finish in a few seconds.
Note: There is a small gap between scanning and actual use — a port that shows as free could be taken by the time you start your server. Always handle
address already in usein your own code.
MIT License
- This tool only scans ports on your own machine (binds to
0.0.0.0locally). - It does not perform network reconnaissance or scan remote hosts.
- The author is not responsible for any misuse.