portcheck

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.

Port already in use?

npx portcheck-cli kill 3000

portcheck shows what holds the port and who started it, asks, then stops it gently (and never touches system processes). It's a safer kill-port, with nothing to install first.

Fixes for the error you're seeing: Node.js, Next.js, Vite · Python, Django, Flask · Docker · Rails, Spring Boot, Go, .NET, PHP · macOS · Windows · Linux

Features

VS Code extension

When a dev server fails because its port is taken, the extension says who holds it and fixes it: stop it and re-run, or re-run on the next free port.

Install Portcheck - Port in Use Fixer from the VS Code Marketplace (search "portcheck" in VS Code) or Open VSX (VSCodium, Cursor, Windsurf). portcheck is built in.

JetBrains plugin

In IntelliJ IDEA, WebStorm, PyCharm, GoLand and the other JetBrains IDEs, when a run configuration fails because its port is taken, a notification names the process and offers Stop it and rerun; the Ports tool window lists every listening port.

▶ Watch the 20-second demo

Install portcheck-jetbrains- .zip from the latest release (Settings → Plugins → ⚙ → Install Plugin from Disk…); it is in review on JetBrains Marketplace (guide).

Browser extension

On every localhost tab, a badge names the process serving it, or says off when nothing is listening; the popup shows who started it and stops it safely.

Install Portcheck - Localhost Port Inspector from Microsoft Edge Add-ons, then run portcheck browser install once. For Chrome, Brave and Chromium, load the zip from the latest release (guide).

Highlights

• Same commands and output on every OS. It replaces lsof -i, netstat -ano, ss -ltnp and kill.
• Built for scripts. --json follows a versioned schema, exit codes are stable, and results go to stdout while messages go to stderr.
• Container- and WSL-aware. Ports published by Docker/Podman or forwarded from WSL show the container or distro, and kill tells you how to stop it there instead of killing the proxy.
• 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

winget (Windows; the package is waiting for Microsoft's review)

winget install roystondwork-dev.portcheck

Scoop (Windows)

scoop bucket add portcheck https://github.com/roystondwork-dev/scoop-bucket scoop install portcheck

npm (any OS): run it without installing

npx portcheck-cli 3000

PyPI (any OS)

pipx install portcheck-tool

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. The checksum file covering every artifact is signed with cosign (keyless), and releases ship SBOMs and SLSA provenance; see verifying downloads.

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, err := inspect.NewSystem().List(ctx, inspect.Filter{Ports: portspec.Single(3000), ListeningOnly: true})

if err != nil { log.Fatal(err) } for _, s := range res.Sockets { if s.Process != nil { // nil when the owner is hidden from your user fmt.Println(s.PID, s.Process.Name) } }

See the library guide for portspec, inspect, freeport, killer, scan, waitfor and containers.

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