kill-port 3000 kills port 30001 on Windows, and other things I found in a 2-million-downloads-a-week package

Description and use

kill-port-safe replaces the popular but buggy kill-port, accurately freeing the specified port, supporting graceful shutdown, and having no external dependencies.

Problem

kill-port 2.0.1 incorrectly kills processes on ports that share a prefix, e.g., freeing port 3000 also kills a process on 30001, and it reports false positives when no process is listening.

Outcome

kill-port-safe accurately frees only the requested port, reports real failures, supports graceful shutdown, and has no external dependencies, making it a reliable replacement for kill-port in CI and development workflows.

Workflow

• 1. Run npx kill-port-safe <port> to free the port.
• 2. Optionally use --graceful to send SIGTERM first.
• 3. The tool reports the killed process or indicates the port is already free.
• 4. It exits 0 on success or 1 on failure, avoiding false positives.

Evidence

kill-port is downloaded about 2.1 million times a week

Source

Both servers were dead. Then I ran it again, with nothing at all on 4471: Process on port 4471 killed

Source

On Windows it runs netstat -nao and keeps lines that match this regular expression: new RegExp(^ *TCP *[^ ]*:${port}, 'gm')

Source

kill-port-safe keeps kill-port's CLI and API, so switching is a one-line change, and it also installs a kill-port command so existing scripts keep working.

Source

It exits 0 when the port is already free, so predev hooks don't fail on a clean machine, and 1 when a kill really fails.

Source