A cross-platform command-line tool for managing processes running on specific ports. Quickly identify and terminate processes to free up ports for development.
--yes flag for automated scriptsnpm install -g portfree
After installation, the pf command will be available globally in your terminal.
npm install portfree
npx pf
Linux/macOS:
lsof command (usually pre-installed)ps command (usually pre-installed)kill command (usually pre-installed)Windows:
netstat command (built into Windows)tasklist command (built into Windows)taskkill command (built into Windows)Simply run the command and follow the prompts:
pf
You'll be prompted to:
# Check a specific port
pf 3000
# Auto-kill processes without confirmation
pf 8080 --yes
# Show detailed output
pf 3000 --verbose
# Show help
pf --help
# Show version
pf --version
$ pf 3000
🔍 Checking port 3000...
📋 Found 1 process using this port:
🔸 Process Details:
PID: 12345
Name: node
User: developer
Protocol: TCP
Command: node server.js
? Do you want to kill this process (PID: 12345)? Yes
🔄 Attempting to terminate process 12345 (node)...
✅ Process 12345 has been successfully terminated
Process: node
Port 3000 should now be available
🎉 Process terminated successfully!
Port 3000 should now be available
$ pf 8080
🔍 Checking port 8080...
📋 Found 3 processes using this port:
🔸 Process 1:
PID: 12345
Name: nginx
User: www-data
Protocol: TCP
🔸 Process 2:
PID: 12346
Name: apache2
User: www-data
Protocol: TCP
🔸 Process 3:
PID: 12347
Name: node
User: developer
Protocol: TCP
Command: node app.js
============================================================
🎯 Process Management Menu
============================================================
? What would you like to do? (Use arrow keys)
❯ Kill Process 1: nginx (PID: 12345) - www-data
Kill Process 2: apache2 (PID: 12346) - www-data
Kill Process 3: node (PID: 12347) - developer
────────────────────────────────────────────────────────
🔥 Kill ALL 3 processes
────────────────────────────────────────────────────────
❌ Cancel (do nothing)
# User selects "Kill Process 3: node (PID: 12347) - developer"
🔄 Attempting to terminate process 12347 (node)...
✅ Process 12347 has been successfully terminated
Process: node
Port 8080 should now be available
📊 2 processes still running on port 8080
============================================================
🎯 Process Management Menu
============================================================
? What would you like to do? (Use arrow keys)
❯ Kill Process 1: nginx (PID: 12345) - www-data
Kill Process 2: apache2 (PID: 12346) - www-data
────────────────────────────────────────────────────────
🔥 Kill ALL 2 processes
────────────────────────────────────────────────────────
❌ Cancel (do nothing)
# User selects "🔥 Kill ALL 2 processes"
⚠️ You are about to kill ALL processes:
1. nginx (PID: 12345) - www-data
2. apache2 (PID: 12346) - www-data
? Are you sure you want to kill all 2 processes? Yes
🔥 Killing all 2 processes...
[1/2] Killing nginx (PID: 12345)...
✅ Successfully killed nginx (PID: 12345)
[2/2] Killing apache2 (PID: 12346)...
✅ Successfully killed apache2 (PID: 12346)
==================================================
📊 Kill All Summary:
==================================================
✅ Successfully killed: 2 processes
❌ Failed to kill: 0 processes
🎉 All processes have been successfully terminated!
Port should now be available
# User selects "❌ Cancel (do nothing)"
✋ Operation cancelled - no processes were terminated
Port 8080 remains in use by 3 processes
$ pf 9999
🔍 Checking port 9999...
✅ Port 9999 is available
No processes are currently using this port
$ pf 3000 --yes
🔍 Checking port 3000...
📋 Found 2 processes using this port:
🔸 Process 1:
PID: 12345
Name: node
User: developer
Protocol: TCP
🔸 Process 2:
PID: 12346
Name: nginx
User: www-data
Protocol: TCP
⚠️ Auto-killing all processes (--yes flag used)...
🔥 Killing all 2 processes...
[1/2] Killing node (PID: 12345)...
✅ Successfully killed node (PID: 12345)
[2/2] Killing nginx (PID: 12346)...
✅ Successfully killed nginx (PID: 12346)
==================================================
📊 Kill All Summary:
==================================================
✅ Successfully killed: 2 processes
❌ Failed to kill: 0 processes
🎉 All processes have been successfully terminated!
Port should now be available
$ pf
? Enter port number: 3000
🔍 Checking port 3000...
📋 Found 1 process using this port:
🔸 Process Details:
PID: 12345
Name: node
User: developer
Protocol: TCP
Command: node server.js
? Do you want to kill this process (PID: 12345)? No
ℹ️ Process not terminated - port remains in use
Process 12345 (node) is still running
$ pf 80
🔍 Checking port 80...
📋 Found 1 process using this port:
🔸 Process Details:
PID: 1234
Name: nginx
User: root
Protocol: TCP
? Do you want to kill this process (PID: 1234)? Yes
🔄 Attempting to terminate process 1234 (nginx)...
❌ Failed to terminate process 1234
Process: nginx
Error: Permission denied when trying to kill process 1234
💡 Permission Issue - Suggestions:
• Use sudo: sudo pf
• Some system processes require root privileges to terminate
When multiple processes are found, you'll see these options:
| Option | Short | Description |
|---|---|---|
--help | -h | Show help information |
--version | -V | Show version number |
--yes | -y | Skip all prompts and kill all processes automatically |
--verbose | -v | Show detailed output and enable debug logging |
PortFree provides clear error messages and suggestions for common issues:
❌ Permission Error
Insufficient privileges to terminate process
💡 Suggestions:
• Use sudo: sudo pf
• Make sure you have permission to terminate the process
## Quick Reference
### Common Scenarios
| Scenario | Command | What Happens |
|----------|---------|--------------|
| Check if port is free | `pf 3000` | Shows port status and any processes |
| Kill specific process | `pf 3000` → Select process from menu | Interactive menu to choose which process |
| Kill all processes | `pf 3000` → Select "Kill ALL" | Kills all processes after confirmation |
| Auto-kill everything | `pf 3000 --yes` | Immediately kills all processes without prompts |
| Interactive port entry | `pf` | Prompts for port number, then shows menu |
| Get help | `pf --help` | Shows all available options and examples |
### Typical Development Workflow
```bash
# Your development server is stuck on port 3000
$ pf 3000
# See what's running and choose what to kill
# Menu appears with options to kill specific processes or all
# After killing processes, port is free for your new server
$ npm start # or whatever starts your development server
### System Errors
```bash
❌ System Error
lsof command not found
💡 Suggestions:
• Install lsof: sudo apt-get install lsof (Ubuntu/Debian) or brew install lsof (macOS)
❌ Validation Error
Port 99999 is out of range. Port must be between 1 and 65535.
💡 Suggestion: Please check your input and try again.
git clone <repository-url>
cd portfree
npm install
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format
# Check formatting
npm run format:check
# Build (lint + test)
npm run build
The project includes comprehensive unit and integration tests:
# Run all tests
npm test
# Run specific test suites
npm test -- --testPathPattern=unit
npm test -- --testPathPattern=integration
# Run tests with coverage report
npm run test:coverage
portfree/
├── bin/
│ └── pf # Global CLI executable
├── src/
│ ├── adapters/ # Platform-specific implementations
│ │ ├── base-adapter.js # Base adapter interface
│ │ ├── unix-adapter.js # Linux/macOS implementation
│ │ └── windows-adapter.js # Windows implementation
│ ├── core/
│ │ └── port-manager.js # Core business logic
│ ├── errors/ # Custom error classes
│ ├── models/
│ │ └── process.js # Process data model
│ ├── utils/ # Utility functions
│ ├── cli.js # CLI interface
│ └── index.js # Main entry point
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
└── package.json
git checkout -b feature/amazing-feature)npm test)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues or have questions:
FAQs
A cross-platform CLI tool for managing processes running on specific ports
We found that portfree demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.