Port Manager

A comprehensive cross-platform port management utility that automatically identifies and terminates processes using specific ports. When automatic termination fails, it provides detailed manual instructions for different operating systems.

Features

• Cross-platform support: Windows, Linux, and macOS
• Multiple detection methods: Socket binding, psutil library, and system commands
• Automatic process termination: Graceful and forceful termination attempts
• Detailed process information: PID, name, command line, and connection details
• Manual instructions: System-specific guidance when automatic termination fails
• Environment-based configuration: Customizable timeouts and behavior via .env file
• Verbose and quiet modes: Configurable output levels

Installation

From Source

git clone <repository-url>
cd kill_port
pip install -r requirements.txt

Using Setup

python setup.py install

This will install the tool with console commands:

• port-manager <port>
• kill-port <port>

Dependencies

• Required: Python 3.6+ with standard library
• Recommended: psutil library for enhanced process management
• Configuration: python-dotenv for environment variable loading

The program includes fallback functionality for systems without psutil.

Usage

Command Line Interface

# Direct execution
python port_manager.py 8080
python port_manager.py --port 3306
python port_manager.py -p 80

# After installation
port-manager 8080
kill-port 3306

Graphical User Interface (GUI)

# Direct execution
python port_manager_gui.py
python run_gui.py

# After installation
port-manager-gui
kill-port-gui

The GUI provides:

• Real-time port monitoring with auto-refresh
• Interactive process list with detailed information
• One-click process termination with confirmation dialogs
• Live operation logging and status updates
• Manual instruction display for failed terminations
• Environment-driven configuration
• Cross-platform native interface

Command Line Options

python port_manager.py <port>          # Basic usage
python port_manager.py -p <port>       # Alternative port specification
python port_manager.py --port <port>   # Long form port specification
python port_manager.py -v <port>       # Verbose mode
python port_manager.py -q <port>       # Quiet mode

Examples

# Check and kill processes on port 8080
python port_manager.py 8080

# Verbose output for debugging
python port_manager.py -v 3306

# Quiet mode for scripting
python port_manager.py -q 80

Configuration

The tool uses environment variables for configuration. Create a .env file in the project directory:

# All timeouts are in seconds
PROCESS_TIMEOUT=10
SOCKET_TIMEOUT=1
FORCE_KILL_TIMEOUT=5
GRACEFUL_KILL_TIMEOUT=3
VERBOSE_OUTPUT=true
DEBUG=false

Configuration Options

• PROCESS_TIMEOUT: Timeout for subprocess operations (default: 10)
• SOCKET_TIMEOUT: Timeout for socket operations (default: 1)
• FORCE_KILL_TIMEOUT: Timeout for force kill operations (default: 5)
• GRACEFUL_KILL_TIMEOUT: Timeout for graceful termination (default: 3)
• VERBOSE_OUTPUT: Enable verbose output (default: true)
• DEBUG: Enable debug mode for detailed error information (default: false)

GUI Configuration Options

• GUI_WINDOW_SIZE: Initial window size (default: 900x700)
• GUI_AUTO_REFRESH_INTERVAL: Auto-refresh interval in seconds (default: 5)
• GUI_MAX_LOG_LINES: Maximum log lines to keep (default: 1000)
• GUI_DEFAULT_PORT: Default port to load on startup
• GUI_AUTO_MONITOR: Enable auto-monitoring on startup (default: false)
• GUI_THEME: GUI theme - default or dark (default: default)
• GUI_CONFIRM_KILLS: Confirm before killing processes (default: true)
• GUI_SHOW_SYSTEM_PROCESSES: Show system processes in GUI (default: true)

How It Works

1. Port Detection: Uses multiple methods to detect if a port is in use:

   • Socket connection attempts
   • Socket binding attempts
   • psutil network connections (if available)
   • System commands (netstat)

2. Process Identification: Discovers processes using the port via:

   • psutil process information (recommended)
   • System-specific commands (lsof, netstat, tasklist)

3. Process Termination: Attempts termination using:

   • psutil graceful and force termination
   • System kill commands (SIGTERM, SIGKILL on Unix; taskkill on Windows)

4. Manual Instructions: Provides detailed, system-specific instructions when automatic termination fails

Supported Platforms

• Windows: Uses netstat, tasklist, taskkill, and wmic
• Linux: Uses netstat, lsof, kill, and /proc filesystem
• macOS: Uses netstat, lsof, kill, and BSD-specific utilities

Security Considerations

This is a defensive security tool designed for legitimate system administration:

• Provides detailed process information before termination
• Attempts graceful termination before forceful killing
• Requires appropriate system privileges for process termination
• Includes comprehensive manual instructions for security-conscious environments
• No network communication or external dependencies beyond system tools

Error Handling

The tool includes comprehensive error handling for:

• Invalid port numbers (1-65535 range validation)
• Permission errors (insufficient privileges)
• Process access denied scenarios
• System command failures
• Network operation timeouts

Output Examples

Successful Termination

Port Manager - Checking port 8080
==================================================
⚠ Port 8080 is currently in use

Found 1 process(es) using port 8080:

  1. PID: 12345
     Name: node.exe
     Status: LISTEN
     Local Address: 127.0.0.1:8080

Attempting to terminate 1 process(es)...
✓ Successfully terminated process 12345 (node.exe)

✓ SUCCESS: Port 8080 is now available
Successfully terminated 1 process(es).

Manual Instructions Required

Port Manager - Checking port 443
==================================================
⚠ Port 443 is currently in use

Found 1 process(es) using port 443:

  1. PID: 4
     Name: System
     Status: LISTEN
     Local Address: 0.0.0.0:443

Attempting to terminate 1 process(es)...
✗ Failed to terminate process 4 (System)

⚠ Port 443 is still in use after termination attempts

============================================================
MANUAL PROCESS TERMINATION REQUIRED
============================================================
[Detailed manual instructions follow...]

Troubleshooting

Common Issues

1. Permission Denied: Run with elevated privileges (sudo/Administrator)
2. Process Not Found: Process may have terminated between detection and kill attempt
3. System Process: Some system processes cannot be terminated and require service management
4. Port Still in Use: Check for parent processes that may respawn the terminated process

Debug Mode

Enable debug mode for detailed error information:

# Set in .env file
DEBUG=true

# Or set environment variable
export DEBUG=true  # Linux/macOS
set DEBUG=true     # Windows

License

MIT License - See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues, questions, or contributions, please use the project's issue tracker.