portkill

Dependency-free Node.js CLI for freeing ports by terminating the processes using them.

Install

npm install -g @dragonpeti53/portkill

Run without installing:

npx @dragonpeti53/portkill 3000

Usage

portkill <port...> [--yes | --force]
pk <port...> [--yes | --force]

Examples:

portkill 3000
portkill 3000 5173 --yes
pk 8080 --force

By default, portkill prints the matching process table and asks before terminating anything. Use --yes or -y to skip confirmation and terminate gracefully. Use --force or -f to skip confirmation, try graceful termination first, then hard-kill any remaining process after 2 seconds.

portkill targets TCP listeners and UDP-bound processes. Established TCP client connections, port ranges, duplicate ports, and non-integer values are not supported.

Flags

• -y, --yes: skip confirmation and gracefully terminate matching processes.
• -f, --force: skip confirmation, terminate gracefully, then hard-kill survivors after 2 seconds.
• -h, --help: show help.
• -v, --version: print the package version.

Platform Notes

macOS and Linux use lsof when available, then fall back to ss or netstat where practical. Windows uses built-in netstat.exe, tasklist.exe, and taskkill.exe.

Permission errors can occur when the matching process belongs to another user or is elevated. Re-run from a shell with the appropriate permissions.

If no process is found using a requested port, portkill prints a success-style message and exits zero unless another requested port fails.

Exit Codes

• 0: success, including requested ports with no matching process.
• 1: runtime failure, permission failure, user cancellation, non-interactive confirmation failure, or failed termination.
• 2: invalid command-line input.

Troubleshooting

• Confirmation is required: stdin is not interactive. Use --yes or --force.
• No supported port discovery command found: install lsof, ss, or netstat.
• permission denied or EPERM: the process likely requires elevated permissions to terminate.

License

MIT