portop

module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 18, 2026 License: MIT

README

portop is an htop-style terminal UI for the TCP and UDP sockets on a machine. For every port it shows the process, its systemd unit or Windows service, its Docker, Podman or Kubernetes container, who can reach it and what the firewall does with it, and it lets you inspect or stop the owner from the keyboard. It runs on Linux, macOS and Windows, in the terminal, in a browser or inside Cockpit.

✨ Features

See what is using your ports

  • A live table of listening and established sockets with process, PID, CPU, user and service names (:22 ssh), sortable by any column.
  • The systemd unit or Windows service, and the Docker, Podman or Kubernetes container behind each socket, read from cgroups with no daemon of its own.
  • One row for a server's master and its workers: nginx +3.
  • Bytes per second for every established TCP connection (Linux, macOS).

Know who can reach them

  • Listening ports colored by exposure: every interface, one address or loopback only.
  • The host firewall's verdict for exposed ports: allowed, restricted to some sources, or blocked.

Act on them

  • Process details, and SIGTERM or SIGKILL after a confirmation that re-checks the process identity.
  • --wait 5432 blocks until a service listens; --free 3000 stops whatever holds a port and waits until it is released.
  • Open a port in the browser, copy a row, filter by any word.

Catch changes

  • New listening ports are highlighted live, with an optional desktop notification.
  • --save-baseline and --diff (exit code 3) report ports that appear, disappear or become reachable from the network, from cron or CI.
  • --compose DIR checks a Docker Compose project's published ports against what actually listens.

Use it anywhere

  • --json for scripts, a web dashboard with sign-in, TLS and Prometheus /metrics, and a Cockpit add-on.
  • 13 themes and remappable keys from a live settings screen.

📥 Install

System Command
Debian, Ubuntu APT repository
Linux (Snap) sudo snap install portop
macOS, Linux brew install portop
Windows winget install padovanl.portop, or the Microsoft Store
Linux, macOS curl -fsSL https://raw.githubusercontent.com/padovanl/portop/main/install.sh | sh
From source go install github.com/padovanl/portop/cmd/portop@latest

The APT repository serves amd64, arm64 and armhf:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://apt.lucapadovan.dev/lucapadovan.gpg | sudo tee /etc/apt/keyrings/lucapadovan.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/lucapadovan.gpg] https://apt.lucapadovan.dev stable main" \
  | sudo tee /etc/apt/sources.list.d/lucapadovan.list
sudo apt update && sudo apt install portop

Release archives cover Linux on amd64, arm64, ARMv7 and ARMv6, macOS on Intel and Apple Silicon, and Windows on x64 and ARM64, with .deb and .rpm packages for Linux. See Installation for every option.

⌨️ Usage

portop                      # the live table
portop nginx 443            # filtered: every word must match
portop --listen             # listening sockets only
portop --json               # one snapshot for scripts

portop --wait 5432          # exit 0 once something listens
portop --free 3000          # stop whatever holds the port

portop --save-baseline      # record what listens now
portop --diff               # exit 3 if that changed
portop --compose ./stack    # audit a Compose project's ports

portop --web                # dashboard on http://127.0.0.1:8088

Run sudo portop (an Administrator terminal on Windows) to see other users' processes and read the firewall. In the table, press ? for help and , for settings. The documentation covers every flag, the JSON fields, exit codes and what each platform supports.

🆚 Why not just ss -tlnp?

ss / netstat lsof bandwhich portop
Live, refreshing view ❌ ❌ ✅ ✅
Owning process ✅ ✅ ✅ ✅
systemd unit, Windows service ❌ ❌ ❌ ✅
Docker, Podman, Kubernetes ❌ ❌ ❌ ✅
Exposure and firewall verdict ❌ ❌ ❌ ✅
Per-connection traffic ✅ -ti ❌ ✅ ✅
Stop the owner, safely ❌ ❌ ❌ ✅
--wait / --free for scripts ❌ ❌ ❌ ✅
Baseline drift, Compose audit ❌ ❌ ❌ ✅
Web dashboard, Prometheus ❌ ❌ ❌ ✅
Linux, macOS and Windows ✅ ❌ ✅ ✅

📚 Documentation

The documentation is generated from docs-src/ with python3 scripts/build-docs.py; preview the whole site with python3 scripts/serve-pages.py.

🤝 Contributing

Pull requests are welcome; see CONTRIBUTING.md. Open them against develop, and run gofmt -l . && go vet ./... && go test ./... before pushing.

📄 License

MIT. See LICENSE.

Directories

Path Synopsis
cmd
portop command
Command portop shows the processes using TCP and UDP ports.
 Command portop shows the processes using TCP and UDP ports.
internal
app
Package app collects sockets and enriches them with process metadata.
 Package app collects sockets and enriches them with process metadata.
baseline
Package baseline implements portop's drift-detection feature: save a snapshot of which ports are currently listening, then later diff the live system against it to see what changed.
 Package baseline implements portop's drift-detection feature: save a snapshot of which ports are currently listening, then later diff the live system against it to see what changed.
cli
Package cli parses flags and runs the TUI, web server, or snapshot commands.
 Package cli parses flags and runs the TUI, web server, or snapshot commands.
compose
Package compose audits Docker Compose published ports against the sockets currently listening on the host.
 Package compose audits Docker Compose published ports against the sockets currently listening on the host.
config
Package config loads and saves portop settings.
 Package config loads and saves portop settings.
dnscache
Package dnscache provides a caching, non-blocking reverse DNS resolver suitable for calling from a UI render loop: a lookup that has not completed yet returns immediately with ok=false and completes in the background, so the UI never stalls on a slow or dead resolver.
 Package dnscache provides a caching, non-blocking reverse DNS resolver suitable for calling from a UI render loop: a lookup that has not completed yet returns immediately with ok=false and completes in the background, so the UI never stalls on a slow or dead resolver.
docker
Package docker reads container metadata from cgroups and the Docker socket.
 Package docker reads container metadata from cgroups and the Docker socket.
firewall
Package firewall reports whether the host firewall lets traffic reach a listening port.
 Package firewall reports whether the host firewall lets traffic reach a listening port.
hostcmd
Package hostcmd runs system inspection tools with a bounded runtime and locale-independent output.
 Package hostcmd runs system inspection tools with a bounded runtime and locale-independent output.
netutil
Package netutil decodes the hex-encoded address/port fields used by Linux's /proc/net/{tcp,tcp6,udp,udp6} pseudo-files.
 Package netutil decodes the hex-encoded address/port fields used by Linux's /proc/net/{tcp,tcp6,udp,udp6} pseudo-files.
notify
Package notify sends best-effort desktop notifications (used by portop's "alert on new listening port" feature).
 Package notify sends best-effort desktop notifications (used by portop's "alert on new listening port" feature).
openurl
Package openurl opens a URL in the user's default browser, on whichever OS portop happens to be running on.
 Package openurl opens a URL in the user's default browser, on whichever OS portop happens to be running on.
procctl
Package procctl sends termination signals to processes by PID, for portop's "k" (kill) action.
 Package procctl sends termination signals to processes by PID, for portop's "k" (kill) action.
procinfo
Package procinfo reads detailed, on-demand information about a single process for the TUI's detail view (Enter on a row): command line, executable path, working directory, owning user, memory usage and start time.
 Package procinfo reads detailed, on-demand information about a single process for the TUI's detail view (Enter on a row): command line, executable path, working directory, owning user, memory usage and start time.
scanner
Package scanner enumerates TCP/UDP sockets and their owning processes.
 Package scanner enumerates TCP/UDP sockets and their owning processes.
services
Package services resolves well-known port numbers to service names (22 -> ssh, 443 -> https) by parsing the system's /etc/services file, so portop can hint at what a port is for even when the owning process can't be resolved (e.g.
 Package services resolves well-known port numbers to service names (22 -> ssh, 443 -> https) by parsing the system's /etc/services file, so portop can hint at what a port is for even when the owning process can't be resolved (e.g.
systemdinfo
Package systemdinfo associates a process with the systemd unit that owns it, by inspecting the process's cgroup membership.
 Package systemdinfo associates a process with the systemd unit that owns it, by inspecting the process's cgroup membership.
terminaltext
Package terminaltext makes untrusted text safe to render in a terminal.
 Package terminaltext makes untrusted text safe to render in a terminal.
traffic
Package traffic reads how many bytes each TCP connection has sent and received, so portop can show per-connection throughput.
 Package traffic reads how many bytes each TCP connection has sent and received, so portop can show per-connection throughput.
ui
Package ui implements portop's Bubble Tea terminal UI: a live, sortable, filterable table of TCP/UDP sockets enriched with process, systemd and Docker context.
 Package ui implements portop's Bubble Tea terminal UI: a live, sortable, filterable table of TCP/UDP sockets enriched with process, systemd and Docker context.
userfile
Package userfile writes portop's per-user files (config.yml, the baseline) so they stay usable by the user who owns them.
 Package userfile writes portop's per-user files (config.yml, the baseline) so they stay usable by the user who owns them.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.