portcheck

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.

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

	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 servers --older-than 1d	The dev servers you forgot: your listening processes with their project and uptime, oldest first; --stop to clean up
📡	portcheck scan db.internal -p 5432	Rate-limited TCP connect checks of remote hosts. No root needed
⏳	portcheck wait db:5432 -t 60s	Block until services accept connections, or until a port is free. Built for CI
▶️	portcheck run --port 3000 --next -- npm run dev	Start a command on a free port ($PORT, {port}); take the next one or stop the holder
🩺	portcheck doctor	Check the ports listed in .portcheck.yaml and get a fix for each problem
🖥️	portcheck	Live, sortable, filterable TUI. Stop processes without leaving it
🌐	Browser extension	Edge (and Chrome): which process serves a localhost tab, off when nothing listens, stop it from the popup (guide)
🧩	VS Code extension	"Port in use" errors in the terminal become one-click fixes; listening ports in the sidebar (guide)
🤖	portcheck mcp	AI assistants (Claude Code, Cursor, Copilot…) check and free ports themselves (guide)
⌨️	Raycast	Search Ports, Check Port, Kill Port and Find Free Port from the Mac launcher
✍️	Neovim	:Portcheck picker, check/kill/free, and "port in use" in :terminal → stop it
🔌	Menu bar / tray app	Your listening ports in the macOS menu bar or Windows/Linux tray: stop, open, copy in two clicks
🧠	JetBrains plugin	IntelliJ IDEA, WebStorm, PyCharm, GoLand…: "port in use" in Run/Debug → Stop it and rerun; a Ports tool window

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-<version>.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