portmap

A terminal UI for viewing everything running on your local ports. See which processes are listening, connected, and what Docker containers they belong to -- all in one interactive dashboard.

Installation

pip install portmap-tui

With Docker container resolution:

pip install portmap-tui[docker]

Quick Start

# Launch the TUI (may need sudo for full process info)
portmap

# With elevated privileges to see all processes
sudo portmap

# JSON snapshot for scripting
portmap --json | jq

# Filter to a specific port or range
portmap --port 8080
portmap --port 3000-9000

CLI Options

Option	Description
-r, --refresh N	Auto-refresh interval in seconds (default: 2)
--no-refresh	Disable auto-refresh
-p, --port PORT	Filter to port or range (e.g. 8080, 3000-9000)
--listen-only	Show only LISTENING sockets
--established-only	Show only ESTABLISHED connections
--no-docker	Skip Docker container resolution
--json	Print JSON snapshot and exit
--version	Show version and exit

Key Bindings

Key	Action
q	Quit
/	Focus search box
l	Toggle LISTEN-only filter
e	Toggle ESTABLISHED-only filter
a	Show all (clear filters)
t / u	TCP only / UDP only
s / S	Cycle sort column / reverse sort
k	Kill selected process
d	Toggle Docker column
r	Refresh now
Enter	Show process detail
?	Help overlay

Docker Support

Docker container names and images are resolved automatically when the Docker daemon is available. Install the docker extra to enable this:

pip install portmap-tui[docker]

On macOS, Docker Desktop runs containers inside a VM, so process PIDs don't match host PIDs. Portmap handles this by falling back to port-based mapping: it queries Docker for published port bindings and matches them to listening ports.

Configuration

Portmap reads an optional config file at ~/.config/portmap/config.toml:

refresh_interval = 2
listen_only = false
established_only = false
no_docker = false
sort_key = "port"        # port, process, pid, status, uptime
sort_reverse = false
show_docker_column = true
theme = "dark"

All fields are optional. CLI flags override config file values.

JSON Mode

portmap --json prints a single snapshot as a JSON array and exits. Each entry includes protocol, address, port, status, PID, process name, command, user, category, uptime, and Docker info (if available). Useful for piping into jq, monitoring scripts, or other tools.

# List all listening ports
portmap --json --listen-only | jq '.[].local_port'

# Find processes on high ports
portmap --json --port 8000-65535 | jq '.[] | {port: .local_port, process: .process_name}'

Requirements

• Python 3.10+
• Works on macOS and Linux
• Some features (full process info, kill) require root/sudo

License

MIT -- see LICENSE for details.