🔪 kport - Cross-Platform Port Inspector and Killer

A powerful, cross-platform command-line tool to inspect, kill, and monitor processes using specific ports — with AI safety shields, Watch Mode, Docker awareness, and an MCP server for AI agent integration.

✨ Features

Core

🔍 Inspect ports - Find which process is using a specific port
🔎 Inspect multiple ports - Check multiple ports at once
🔍 Inspect port range - Scan a range of ports (e.g., 3000-3010)
🔎 Inspect by process name - Find all processes matching a name and their ports
🔪 Kill processes - Terminate processes using specific ports
💥 Kill port range - Terminate processes on a range of ports
🔫 Kill multiple ports - Kill processes on multiple ports at once
🎯 Kill by process name - Kill all processes matching a name (e.g., "node", "python")
📋 List all ports - View all listening ports and their processes
🐳 Docker-aware - Detect ports published by Docker containers (even when you don't see a host process)
🎨 Colorized output - Easy-to-read colored terminal output
✅ Confirmation prompts - Safety confirmation before killing processes
🌍 Cross-platform - Works on Windows, Linux, and macOS

Pro Features (v4.0.0)

🖥️ Interactive TUI Picker (kport -I / kport interactive) - Visual TUI with fuzzy search filter, multi-select, and batch kill execution.
⚙️ Process Manager Awareness - cgroup-detects systemd unit services (systemd:unit), PM2 apps (pm2:app), and Supervisord tasks with auto-restart warning/prevention info.
⏱️ Watch Mode Enhancements - --until free|occupied blocks execution until condition met, with --timeout gate.
🌐 UDP Protocol Support - inspect, list, kill, watch, or detect conflicts using --proto tcp|udp|both.
🌳 Process Tree Kill - --kill-tree depth-first recursive child process termination.
⏳ Wait for Exit - --wait-for-exit <sec> verifies the socket is fully closed/released.
👁️ Watch Mode - Monitor ports in real-time and auto-kill on new connections.
🛡️ Safety Shield - Block kills on critical system ports (SSH, DNS, DB, K8s) and protected processes by default.
⚙️ Config File - Set persistent defaults via .kport.json (project, home, or global).
🔓 Bypass Safety - Override safety shields with --bypass-safety when needed.
🤖 MCP Server - Model Context Protocol server for AI agent integration (Claude, Copilot, Cursor, etc.).
📦 Cross-platform packaging - Native builds for Windows (.exe), macOS (.pkg), Debian (.deb), and RPM.

📦 Installation

Pre-compiled platform-native packages are available on the GitHub Releases page.

Platform	Format	Quick Install
🪟 Windows	`.exe` Setup Wizard	Download and run `kport-setup.exe` (adds to PATH)
🍎 macOS	`.pkg` Installer	Download and run `kport.pkg`
🐧 Debian / Ubuntu	`.deb` Package	`sudo dpkg -i kport_*.deb`
🐧 RHEL / Fedora	`.rpm` Package	`sudo rpm -i kport-*.rpm`
🌍 Python (Any OS)	PyPI Package	`pip install --user kport`

Installing via pip (PyPI)

# Recommended: Install to user directory
pip install --user kport

# Or install system-wide (requires admin/sudo)
pip install kport

Install from GitHub

pip install --user git+https://github.com/farman20ali/port-killer.git

Install from Source

# Clone the repository
git clone https://github.com/farman20ali/port-killer.git
cd port-killer

# Install to user directory (recommended)
pip install --user .

Run Without Installing

python -m kport -h

💡 Tip: If the kport command doesn't work after installation, see TROUBLESHOOTING.md

📖 For detailed platform installation options, see docs/INSTALL.md

🛠️ For packaging development and local compilation instructions, see docs/PACKAGING.md

🚀 Usage

Core commands (Docker-aware by default)

# Inspect a port (local or docker)
kport inspect 8080

# Explain why a port is blocked
kport explain 8080

# Safely free a port (will offer docker stop/restart/remove if needed)
kport kill 8080

# List ports (local + docker)
kport list

# List docker published ports
kport docker

# Detect port conflicts (docker + local)
kport conflicts

Note: --json, --dry-run, --yes, and --debug work with all subcommands.

👁️ Watch Mode (v3.2.0)

Continuously monitor a port and automatically kill any process that starts using it:

# Watch port 8080 and auto-kill any process that binds to it (check every 1s)
kport watch 8080

# Watch with custom interval (every 2.5 seconds)
kport watch 8080 --interval 2.5

# Watch in dry-run mode (just print alerts, don't kill)
kport watch 8080 --dry-run

# Watch with JSON output (for CI/automation)
kport watch 8080 --json

🛡️ Safety Shield (v3.2.0)

The Safety Shield prevents accidental termination of critical system services:

# This will be BLOCKED by the Safety Shield (port 22 = SSH):
kport kill 22
# Output: 🛡️ Security Shield Active: Port 22 is a protected port.

# Override the shield when you REALLY need to (use with caution):
kport kill 22 --bypass-safety

# The shield also protects critical processes:
kport kill 8080
# Output if sshd or docker is found: 🛡️ Security Shield: critical process 'docker' ...

Default protected ports: 22 (SSH), 53 (DNS), 80 (HTTP), 443 (HTTPS), 3306 (MySQL), 5432 (PostgreSQL), 6379 (Redis), 6443 (Kubernetes API)

Default protected processes: systemd, init, docker, dockerd, sshd, explorer.exe, lsass.exe, services.exe

🤖 MCP Server (AI Agent Integration)

Run kport as an MCP server so AI assistants can inspect and free ports on your behalf:

# Start the MCP server (stdio transport)
kport --mcp
# or
python -m kport.mcp_server

Available MCP tools:

list_ports — List all active listening ports (local + Docker)
inspect_port — Detailed info about a specific port
kill_port — Free a port (always respects the Safety Shield)

Configure in Claude Desktop / Cursor / VS Code Copilot:

{
  "mcpServers": {
    "kport": {
      "command": "kport",
      "args": ["--mcp"]
    }
  }
}

Why a port may show without PID

On Linux, some ports may appear as LISTEN but the owning PID/process name is not visible without elevated privileges (common with system services).

If you see local-unknown in inspect / explain, try:

sudo -E kport inspect 6379
sudo -E kport explain 6379

If you installed with pip install --user kport, sudo may not find kport because root's PATH doesn't include your user scripts directory.

Alternatives:

# Option 1: keep your PATH when using sudo
sudo -E "$HOME/.local/bin/kport" inspect 6379

# Option 2: run the module via the system python (when working from repo)
sudo -E python3 -m kport inspect 6379

⚙️ Config file support

Set persistent defaults via a JSON config file (searched in this priority order):

.kport.json (current directory — project-level)
~/.kport.json (user-level)
~/.config/kport/config.json (XDG-compliant)

Full example config:

{
  "yes": true,
  "dry_run": false,
  "force": false,
  "graceful_timeout": 5,
  "docker_action": "stop",
  "protected_ports": [8080, 9090],
  "protected_processes": ["my-critical-app", "postgres"]
}

Note: Setting protected_ports or protected_processes in your config replaces (not extends) the default Safety Shield lists.

Inspect a port

Find out which process is using a specific port:

kport -i 8080

Example output:

🔍 Inspecting port 8080...

✓ Port 8080 is being used by PID 12345

Process Information:
──────────────────────────────────────────────────
PID: 12345
Image Name: node.exe
Session Name: Console
Mem Usage: 45,678 K

Inspect by process name

Find all processes matching a name and see what ports they're using:

kport -ip node

Example output:

🔍 Inspecting processes matching 'node'...

Found 3 connection(s) for processes matching 'node':

PID        Process                   Port       State          
──────────────────────────────────────────────────────────────────────
12345      node.exe                  3000       LISTENING      
                                     3001       LISTENING      
12346      node.exe                  8080       LISTENING      

✓ Total processes found: 2
✓ Total connections: 3

Inspect multiple ports

Check multiple ports at once:

kport -im 3000 3001 8080 8081

Example output:

🔍 Inspecting 4 port(s)...

Port       PID        Process                       
────────────────────────────────────────────────────────────
3000       12345      node.exe                      
3001       12346      node.exe                      
8080       12347      python.exe                    

✓ Found processes on 3/4 port(s)

Inspect port range

Scan a range of ports:

kport -ir 3000-3010

Example output:

🔍 Inspecting port range 3000-3010 (11 ports)...

Port       PID        Process                       
────────────────────────────────────────────────────────────
3000       12345      node.exe                      
3001       12346      node.exe                      
3005       12347      python.exe                    

✓ Found processes on 3/11 port(s) in range

Kill a process on a port

Terminate the process using a specific port:

kport -k 8080

Example output:

🔪 Attempting to kill process on port 8080...

Found PID 12345 using port 8080

Process to be terminated:
PID: 12345
Image Name: node.exe

Are you sure you want to kill this process? (y/N): y

✓ Successfully killed process 12345
Port 8080 is now free.

List all listening ports

View all active listening ports and their associated processes:

kport -l

Example output:

📋 Listing all active ports...

Protocol   Local Address            State           PID       
──────────────────────────────────────────────────────────────────────
TCP        0.0.0.0:80               LISTENING       1234      
TCP        0.0.0.0:443              LISTENING       1234      
TCP        0.0.0.0:3000             LISTENING       5678      
TCP        0.0.0.0:8080             LISTENING       9012

Kill by process name

Kill all processes matching a specific name:

kport -kp node

Example output:

🔪 Killing all processes matching 'node'...

Found 3 process(es) matching 'node':
──────────────────────────────────────────────────
  PID 12345: node.exe
  PID 12346: node.exe
  PID 12347: node.exe

Are you sure you want to kill 3 process(es)? (y/N): y

✓ Killed PID 12345
✓ Killed PID 12346
✓ Killed PID 12347

✓ Successfully killed 3/3 process(es)

Kill multiple ports at once

Kill processes on multiple ports simultaneously:

kport -ka 3000 3001 3002

Example output:

🔪 Killing processes on 3 port(s)...

Found processes on 3 port(s):
──────────────────────────────────────────────────
  Port 3000: PID 12345 (node.exe)
  Port 3001: PID 12346 (node.exe)
  Port 3002: PID 12347 (python.exe)

Are you sure you want to kill 3 process(es)? (y/N): y

✓ Killed process on port 3000 (PID 12345)
✓ Killed process on port 3001 (PID 12346)
✓ Killed process on port 3002 (PID 12347)

✓ Successfully killed 3/3 process(es)
Ports freed: 3000, 3001, 3002

Kill port range

Kill all processes on a range of ports:

kport -kr 3000-3010

Example output:

🔪 Killing processes on port range 3000-3010 (11 ports)...

Found processes on 3 port(s) in range:
──────────────────────────────────────────────────
  Port 3000: PID 12345 (node.exe)
  Port 3001: PID 12346 (node.exe)
  Port 3005: PID 12347 (python.exe)

Are you sure you want to kill 3 process(es)? (y/N): y

✓ Killed process on port 3000 (PID 12345)
✓ Killed process on port 3001 (PID 12346)
✓ Killed process on port 3005 (PID 12347)

✓ Successfully killed 3/3 process(es)
Ports freed: 3000, 3001, 3005

Show help

kport -h

Show version

kport -v

📚 Command-Line Reference

Subcommands (Recommended)

Subcommand	Description
`kport list`	List all listening ports (local + Docker)
`kport inspect PORT`	Inspect port (local or Docker)
`kport explain PORT`	Explain why a port is occupied (with conflict analysis)
`kport kill PORT`	Free a port (safety-shielded, Docker-aware)
`kport watch PORT`	Monitor port in real-time and auto-kill on activity
`kport docker`	List Docker-published ports
`kport conflicts`	Detect port conflicts between Docker and local processes

Subcommand Flags

Flag	Commands	Description
`--json`	all	Output results as JSON
`--dry-run`	kill, watch	Simulate actions without killing
`--yes`	kill, watch	Skip confirmation prompts
`--force`	kill, watch	Force kill (SIGKILL after SIGTERM)
`--debug`	all	Enable verbose debug output
`--bypass-safety`	kill, watch	Override Safety Shield for protected ports/processes
`--interval SECS`	watch	Poll interval in seconds (default: 1.0)
`--graceful-timeout SECS`	kill, watch	Seconds to wait for graceful shutdown (default: 3.0)
`--docker-action`	kill	Docker action: `stop`, `restart`, or `rm`
`--mcp`	(root flag)	Start the MCP JSON-RPC server on stdio

Legacy Flags (still supported)

Option	Long Form	Description
`-i PORT`	`--inspect PORT`	Inspect which process is using the specified port
`-im PORT [PORT ...]`	`--inspect-multiple PORT [PORT ...]`	Inspect multiple ports at once
`-ir RANGE`	`--inspect-range RANGE`	Inspect port range (e.g., 3000-3010)
`-ip NAME`	`--inspect-process NAME`	Inspect all processes matching the given name and their ports
`-k PORT`	`--kill PORT`	Kill the process using the specified port
`-kp NAME`	`--kill-process NAME`	Kill all processes matching the given name
`-ka PORT [PORT ...]`	`--kill-all PORT [PORT ...]`	Kill processes on multiple ports at once
`-kr RANGE`	`--kill-range RANGE`	Kill processes on port range (e.g., 3000-3010)
`-l`	`--list`	List all listening ports and their processes
`-v`	`--version`	Show version information
`-h`	`--help`	Show help message

🛠️ Requirements

Python 3.8 or higher
No mandatory external dependencies (uses only Python standard library by default)

Optional Dependencies

Package	Purpose	Install
`psutil`	Faster, richer process info	`pip install psutil`
`mcp`	MCP server SDK (alternative transport)	`pip install mcp`

Platform-specific tools (fallback if psutil not available)

Windows: netstat, tasklist, taskkill
Linux/macOS: lsof, ss, fuser, ps, kill

These tools are typically pre-installed on all platforms.

🔧 Development

Setup & Local Development

We provide a unified task runner manage.py at the root of the project to simplify development tasks:

# 1. Clone the repository
git clone https://github.com/farman20ali/port-killer.git
cd port-killer

# 2. Set up the development environment (installs package in editable mode and dev dependencies)
python manage.py setup

Running Tests

# Run the test suite (uses pytest, falls back to lightweight runner if not installed)
python manage.py test

📚 Documentation

Installation Guide - Detailed installation instructions
Quick Start - Get started quickly
Packaging Guide - Cross-platform binary and package builds
Publishing Guide - How to publish kport to PyPI
Release Guide - Creating releases (manual & automated)
Release Notes v3.2.0 - What's new in 3.2.0
Contributing - How to contribute

🚀 For Maintainers

Creating and Publishing a Release

Everything is managed via the manage.py entrypoint. To prepare a release:

Update the version number across metadata files:
```
python manage.py sync-version <version>
```
Tag a new Git release (which triggers GitHub Actions compilation) and publish packages:
```
python manage.py publish --release-tag <version>
```

You can also run python manage.py without arguments to access the interactive menu for all setup, build, publish, test, and release tasks.

See docs/RELEASE_GUIDE.md for detailed manual steps and troubleshooting.

🤝 Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

What this means:

✅ Free to use, modify, and distribute
✅ Can use in proprietary/commercial software without open-sourcing your code
✅ Must preserve copyright notices and attribution
✅ Must include a copy of the license in distributions
❌ Contributors do not grant patent rights beyond what's needed to use the software

For questions or commercial inquiries, contact: alienhub.dev@gmail.com

⚠️ Important Notes

Administrator/sudo privileges: Killing processes may require elevated privileges on some systems
Port validation: Port numbers must be between 1 and 65535
Safety: The tool asks for confirmation before killing any process
Multiple processes: If multiple processes use the same port, the first one found will be shown/killed

🐛 Troubleshooting

"Permission denied" errors

On Linux/macOS, you may need to run with sudo:

sudo kport -k 80

On Windows, run your terminal as Administrator.

Stubborn processes that won't die

Some processes (especially Java applications) may not respond to graceful termination. Use the --force flag which automatically uses a multi-tier kill strategy (SIGTERM → SIGKILL → fuser):

kport -k 8081 --force

On Linux, kport will automatically use fuser -k as a fallback when standard kill methods fail. This is extremely effective for stubborn Java/Node/Python processes:

# Install fuser for best results (Ubuntu/Debian)
sudo apt-get install psmisc

# Install fuser (RHEL/CentOS/Fedora)
sudo yum install psmisc

# Then kport will automatically use it when needed
kport -k 8081 --force

What happens:

First tries SIGTERM (graceful shutdown)
Then tries SIGKILL after timeout
Finally uses fuser -k 8081/tcp if process still lives (Linux only)

Manual alternative: You can also kill a port directly with fuser:

# Kill all processes using port 8081 (requires sudo)
sudo fuser -k 8081/tcp

Port not found

Make sure the port number is correct and that a process is actually using it. Use kport -l to see all active ports.

Color output not working on Windows

Colors should work on Windows 10 and later. If you're on an older version, colors may not display correctly.

📧 Contact

Farman Ali Ujjan - [alienhub.dev@gmail.com]

Project Link: https://github.com/farman20ali/port-killer

Made with ❤️ for developers who are tired of hunting down processes

`kport --help`

usage: python3 -m kport [-h] [--json] [--dry-run] [-y] [--debug]
                        [--config CONFIG] [--bypass-safety] [-i PORT]
                        [-im PORT [PORT ...]] [-ir RANGE] [-ip NAME] [-k PORT]
                        [-kp NAME] [-ka PORT [PORT ...]] [-kr RANGE] [-l]
                        [--exact] [--force]
                        [--graceful-timeout GRACEFUL_TIMEOUT]
                        [--wait-for-exit SECONDS] [--kill-tree]
                        [--proto {tcp,udp,both}] [-I] [-v] [--mcp]
                        {inspect,explain,kill,kill-process,list,docker,conflicts,watch,mcp,interactive,completion} ...

kport - Cross-platform port inspector and killer

positional arguments:
  {inspect,explain,kill,kill-process,list,docker,conflicts,watch,mcp,interactive,completion}
    inspect             Inspect a port (docker-aware)
    explain             Explain why a port is blocked
    kill                Safely free a port (docker-aware)
    kill-process        Kill processes by name
    list                List active ports (local + docker)
    docker              List Docker-published ports
    conflicts           Detect docker/local port conflicts
    watch               Live monitoring of port ownership
    mcp                 Start the stdio Model Context Protocol (MCP) server
    interactive         Launch interactive TUI port picker
    completion          Generate shell autocompletion scripts

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  -i, --inspect PORT    Inspect specified port
  -im, --inspect-multiple PORT [PORT ...]
                        Inspect multiple ports
  -ir, --inspect-range RANGE
                        Inspect port range
  -ip, --inspect-process NAME
                        Inspect processes by name
  -k, --kill PORT       Kill processes using port
  -kp, --kill-process NAME
                        Kill processes by name
  -ka, --kill-all PORT [PORT ...]
                        Kill multiple ports
  -kr, --kill-range RANGE
                        Kill processes on range
  -l, --list            List all listening ports
  --exact               Exact process name matching
  --force               Force kill stubborn processes (SIGKILL / fuser)
  --graceful-timeout GRACEFUL_TIMEOUT
                        Seconds to wait before force kill (default: 3.0)
  --wait-for-exit SECONDS
                        Wait for port to be free after killing (up to N
                        seconds)
  --kill-tree           Kill the process and all of its descendants
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)
  -I, --interactive     Launch interactive TUI port picker
  -v, --version         show program's version number and exit
  --mcp                 Start the MCP JSON-RPC server on stdio (alias for
                        'kport mcp')

Examples:
  kport -i 8080
  kport -im 3000 3001 3002
  kport -ir 3000-3010
  kport -k 8080 --yes
  kport inspect 8080
  kport kill 8080 --force
  kport mcp

`kport inspect --help`

usage: python3 -m kport inspect [-h] [--json] [--dry-run] [-y] [--debug]
                                [--config CONFIG] [--bypass-safety]
                                [--proto {tcp,udp,both}] [--profile PROFILE]
                                [port]

positional arguments:
  port

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)
  --profile PROFILE     Named port profile from config

`kport explain --help`

usage: python3 -m kport explain [-h] [--json] [--dry-run] [-y] [--debug]
                                [--config CONFIG] [--bypass-safety]
                                [--proto {tcp,udp,both}]
                                port

positional arguments:
  port

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)

`kport kill --help`

usage: python3 -m kport kill [-h] [--json] [--dry-run] [-y] [--debug]
                             [--config CONFIG] [--bypass-safety]
                             [--proto {tcp,udp,both}] [--profile PROFILE]
                             [--docker-action {stop,restart,rm}] [--force]
                             [--graceful-timeout GRACEFUL_TIMEOUT]
                             [--wait-for-exit SECONDS] [--kill-tree]
                             [port]

positional arguments:
  port

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)
  --profile PROFILE     Named port profile from config
  --docker-action {stop,restart,rm}
                        Action when port belongs to Docker
  --force
  --graceful-timeout GRACEFUL_TIMEOUT
  --wait-for-exit SECONDS
                        Wait for port to be free after killing (up to N
                        seconds)
  --kill-tree           Kill the process and all of its descendants

`kport kill-process --help`

usage: python3 -m kport kill-process [-h] [--json] [--dry-run] [-y] [--debug]
                                     [--config CONFIG] [--bypass-safety]
                                     [--proto {tcp,udp,both}] [--exact]
                                     [--force]
                                     [--graceful-timeout GRACEFUL_TIMEOUT]
                                     [--kill-tree]
                                     name

positional arguments:
  name

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)
  --exact
  --force
  --graceful-timeout GRACEFUL_TIMEOUT
  --kill-tree           Kill the process and all of its descendants

`kport list --help`

usage: python3 -m kport list [-h] [--json] [--dry-run] [-y] [--debug]
                             [--config CONFIG] [--bypass-safety]
                             [--proto {tcp,udp,both}]

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)

`kport docker --help`

usage: python3 -m kport docker [-h] [--json] [--dry-run] [-y] [--debug]
                               [--config CONFIG] [--bypass-safety]
                               [--proto {tcp,udp,both}]

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)

`kport conflicts --help`

usage: python3 -m kport conflicts [-h] [--json] [--dry-run] [-y] [--debug]
                                  [--config CONFIG] [--bypass-safety]
                                  [--proto {tcp,udp,both}]

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)

`kport watch --help`

usage: python3 -m kport watch [-h] [--json] [--dry-run] [-y] [--debug]
                              [--config CONFIG] [--bypass-safety]
                              [--proto {tcp,udp,both}]
                              [--ports PORTS [PORTS ...]] [--range RANGE]
                              [--interval INTERVAL] [--notify]
                              [--until {free,occupied}] [--timeout TIMEOUT]
                              [port]

positional arguments:
  port

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)
  --ports PORTS [PORTS ...]
                        Multiple ports to watch
  --range RANGE         Range of ports to watch (e.g. 3000-3010)
  --interval INTERVAL   Polling interval in seconds
  --notify              Send OS desktop notification on state change
  --until {free,occupied}
                        Block until port matches state ('free' or 'occupied')
                        and exit 0
  --timeout TIMEOUT     Maximum time in seconds to wait when using --until

`kport interactive` Usage & Controls

Launch the interactive TUI picker with kport -I or kport interactive.

Search-by-Default: Start typing characters immediately to filter the active port list by Port, PID, Process Name, or Process Manager.
Navigation: Use the [Up]/[Down] arrow keys to scroll the list (automatically handles viewport scrolling for long lists).
Multi-Select: Press [Space] to toggle selection on the highlighted item.
Refresh/Reload: Press [Ctrl-r] or type /r to reload the active port list, preserving current selections and scrolling back to the top.
Batch Kill & Safety Prompt: Press [Enter] to proceed. kport will exit the curses TUI, display a summary of selected ports/processes, and request confirmation: Are you sure you want to proceed with terminating these target(s)? (y/N)
- Use the CLI option -y or --yes to bypass this prompt.
Quit: Type /q, press [Esc] (clears search query first, then exits on next [Esc]), or use [Ctrl-c] to cancel and exit.

`kport interactive --help`

usage: python3 -m kport interactive [-h] [--json] [--dry-run] [-y] [--debug]
                                    [--config CONFIG] [--bypass-safety]
                                    [--proto {tcp,udp,both}]

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)

`kport mcp --help`

usage: python3 -m kport mcp [-h] [--json] [--dry-run] [-y] [--debug]
                            [--config CONFIG] [--bypass-safety]
                            [--proto {tcp,udp,both}]

options:
  -h, --help            show this help message and exit
  --json                Output machine-readable JSON
  --dry-run             Show actions without executing
  -y, --yes             Skip confirmation prompts
  --debug               Verbose internal logs
  --config CONFIG       Path to JSON config file
  --bypass-safety       Bypass safety shields on protected ports/processes
  --proto {tcp,udp,both}
                        Protocol type: tcp, udp, or both (default: tcp)

Name		Name	Last commit message	Last commit date
.github		.github
assets/icons		assets/icons
benchmarks		benchmarks
docs		docs
packaging		packaging
scripts		scripts
src/kport		src/kport
tests		tests
vscode-extension		vscode-extension
.gitignore		.gitignore
.vfox.toml		.vfox.toml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
__main__.py		__main__.py
manage.py		manage.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

🔪 kport - Cross-Platform Port Inspector and Killer

✨ Features

Core

Pro Features (v4.0.0)

📦 Installation

Installing via pip (PyPI)

Install from GitHub

Install from Source

Run Without Installing

🚀 Usage

Core commands (Docker-aware by default)

👁️ Watch Mode (v3.2.0)

🛡️ Safety Shield (v3.2.0)

🤖 MCP Server (AI Agent Integration)

Why a port may show without PID

⚙️ Config file support

Inspect a port

Inspect by process name

Inspect multiple ports

Inspect port range

Kill a process on a port

List all listening ports

Kill by process name

Kill multiple ports at once

Kill port range

Show help

Show version

📚 Command-Line Reference

Subcommands (Recommended)

Subcommand Flags

Legacy Flags (still supported)

🛠️ Requirements

Optional Dependencies

Platform-specific tools (fallback if psutil not available)

🔧 Development

Setup & Local Development

Running Tests

📚 Documentation

🚀 For Maintainers

Creating and Publishing a Release

🤝 Contributing

📝 License

⚠️ Important Notes

🐛 Troubleshooting

"Permission denied" errors

Stubborn processes that won't die

Port not found

Color output not working on Windows

📧 Contact

kport --help

kport inspect --help

kport explain --help

kport kill --help

kport kill-process --help

kport list --help

kport docker --help

kport conflicts --help

kport watch --help

kport interactive Usage & Controls

kport interactive --help

kport mcp --help

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`kport --help`

`kport inspect --help`

`kport explain --help`

`kport kill --help`

`kport kill-process --help`

`kport list --help`

`kport docker --help`

`kport conflicts --help`

`kport watch --help`

`kport interactive` Usage & Controls

`kport interactive --help`

`kport mcp --help`