README
¶
portcheck
See what's using your ports, find free ones, free them up, and check remote hosts.
One static binary for macOS, Linux and Windows.
Features
| Command | ||
|---|---|---|
| 🔍 | portcheck list -l |
Every listening socket with its process, PID and user |
| ✅ | portcheck 3000 |
Is the port free? If not, who holds it? Exit code 0 or 1 for scripts |
| 🆓 | portcheck free 3000-3999 -n 3 |
Free ports, verified by actually binding them |
| 🛑 | portcheck kill 8080 |
Graceful SIGTERM, then SIGKILL; refuses PID 1, your shell and system processes |
| 📡 | portcheck scan db.internal -p 5432 |
Rate-limited TCP connect checks of remote hosts. No root needed |
| 🖥️ | portcheck |
Live, sortable, filterable TUI. Stop processes without leaving it |
- Same commands and output on every OS. It replaces
lsof -i,netstat -ano,ss -ltnpandkill. - Built for scripts.
--jsonfollows a versioned schema, exit codes are stable, and results go to stdout while messages go to stderr. - Honest about permissions. Hidden owners are shown as hidden, with a hint on how to see them.
- A Go library too. See
pkg/.
Install
# Homebrew (macOS, Linux)
brew install roystondwork-dev/tap/portcheck
# Scoop (Windows)
scoop bucket add portcheck https://github.com/roystondwork-dev/scoop-bucket
scoop install portcheck
# Go 1.26+
go install github.com/roystondwork-dev/portcheck/cmd/portcheck@latest
.deb, .rpm, .apk and archives for amd64/arm64 are on the
releases page. All
artifacts are signed with cosign and ship with SBOMs and SLSA provenance; see
verifying downloads.
Note: until
v0.1.0is released, usego install.
Quickstart
$ portcheck 3000
PORT PROTO STATUS PID PROCESS USER
3000 tcp in-use 42379 node alice
$ portcheck kill 3000
About to terminate:
PID 42379 node (port 3000)
Proceed? [y/N] y
PID PROCESS RESULT DETAIL
42379 node terminated
$ portcheck free 3000-3999 -n 2 -o plain
PORT
3000
3001
$ portcheck list -l --json | jq '.data.sockets[] | {port: .localPort, name: .process.name}'
📖 Documentation: https://roystondwork-dev.github.io/portcheck/ (quickstart · guides · CLI reference · permissions by OS · FAQ)
Use as a Go library
res, _ := inspect.NewSystem().List(ctx, inspect.Filter{Ports: portspec.Single(3000), ListeningOnly: true})
for _, s := range res.Sockets {
fmt.Println(s.PID, s.Process.Name)
}
See the library guide for portspec, inspect, freeport, killer and scan.
Responsible use
portcheck scan makes ordinary TCP connections and has no stealth features. Only
scan hosts and networks you own or are authorized to test.
Contributing
Contributions are welcome! See CONTRIBUTING.md for setup and standards (every change is tested on Linux, macOS and Windows, with a 100% coverage gate on the library), and TASKS.md for the roadmap and status. Please follow the Code of Conduct, and report vulnerabilities privately as described in SECURITY.md.
License
MIT © 2026 Royston D and portcheck contributors
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
portcheck
command
Command portcheck shows what is using your ports, finds free ones, frees them up, and checks ports on remote hosts.
|
Command portcheck shows what is using your ports, finds free ones, frees them up, and checks ports on remote hosts. |
|
internal
|
|
|
buildinfo
Package buildinfo reports the version, commit and build date of the running portcheck binary.
|
Package buildinfo reports the version, commit and build date of the running portcheck binary. |
|
cli
Package cli implements the portcheck command line interface.
|
Package cli implements the portcheck command line interface. |
|
cli/gendocs
command
Command gendocs writes portcheck's CLI reference as Markdown (for the docs site) and man pages.
|
Command gendocs writes portcheck's CLI reference as Markdown (for the docs site) and man pages. |
|
output
Package output renders command results as tables, plain text, CSV or JSON.
|
Package output renders command results as tables, plain text, CSV or JSON. |
|
testutil
Package testutil holds helpers shared by portcheck's tests.
|
Package testutil holds helpers shared by portcheck's tests. |
|
tui
Package tui implements portcheck's interactive terminal UI: a live, sortable, filterable table of sockets from which processes can be stopped.
|
Package tui implements portcheck's interactive terminal UI: a live, sortable, filterable table of sockets from which processes can be stopped. |
|
pkg
|
|
|
freeport
Package freeport determines whether local ports are free and finds free ones.
|
Package freeport determines whether local ports are free and finds free ones. |
|
inspect
Package inspect lists local network sockets together with the processes that own them.
|
Package inspect lists local network sockets together with the processes that own them. |
|
killer
Package killer terminates processes safely.
|
Package killer terminates processes safely. |
|
portspec
Package portspec parses and represents sets of TCP/UDP port numbers.
|
Package portspec parses and represents sets of TCP/UDP port numbers. |
|
scan
Package scan checks which TCP ports are reachable on remote hosts.
|
Package scan checks which TCP ports are reachable on remote hosts. |