DEV Community

Jawad Khan
Jawad Khan

Posted on

I Built LocalhostKiller to Solve Port Conflicts

#cli #productivity #showdev #tooling

Every developer knows the frustration: you're ready to test your latest project, you run npm start, and then—Error: Port 3000 is already in use. You know you have something running on that port, but finding and killing it is a tedious dance of lsof, ps, and kill commands.

I got tired of this. So I built LocalhostKiller—a dead-simple CLI tool to instantly identify and terminate processes hogging your local ports.

The Problem

Port conflicts are deceptively annoying. They interrupt your flow, waste minutes on busywork, and force you to context-switch just to clean up a zombie process. Whether it's a crashed Node.js server, a lingering Docker container, or that Python script you forgot about, these orphaned processes accumulate and become friction in your development workflow.

The Solution

LocalhostKiller is a zero-config CLI that does one thing well: find and kill processes by port number.

pip install localhostkiller
Enter fullscreen mode Exit fullscreen mode

Or install from source:

git clone https://github.com/codebyjawad/localhostkiller.git
cd localhostkiller
pip install -e .
Enter fullscreen mode Exit fullscreen mode

Usage

Interactive Mode 

lhk
Enter fullscreen mode Exit fullscreen mode

Select processes from a menu and kill them interactively.

Kill by Port 

lhk 3000
Enter fullscreen mode Exit fullscreen mode

Instantly kill whatever is running on port 3000.

List All Ports 

lhk --list
Enter fullscreen mode Exit fullscreen mode

See everything running on localhost.

That's it. No flags to remember, no multi-step process hunting.

How It Works

Under the hood, LocalhostKiller:

  1. Scans the specified port across all network interfaces
  2. Identifies the process ID (PID) bound to that port
  3. Gracefully terminates the process (with force-kill fallback)
  4. Confirms the port is now free

It handles the cross-platform quirks so you don't have to—whether you're on macOS, Linux, or Windows.

Why I Built It

I wanted something faster than Stack Overflow. Sure, you can memorize the lsof -ti:3000 | xargs kill -9 incantation, but that's not the point. Developer tools should reduce cognitive load, not add to it. LocalhostKiller is my contribution to that philosophy: a tiny utility that removes one small friction point from the development experience.

Get It

LocalhostKiller is open source and available on npm:

GitHub: github.com/codebyjawad/localhostkiller

npm install -g localhostkiller
Enter fullscreen mode Exit fullscreen mode

If port conflicts slow you down, give it a try. Pull requests welcome.

Top comments (0)