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