Port already in use? Find and stop the process¶

Something is already listening on the port your app wants. To see what it is and stop it, run this. Nothing needs to be installed first:

npx portcheck-cli kill 3000

About to terminate:
  PID 42379  node  (port 3000), started by npm (4200) ← zsh (900)
Proceed? [y/N] y
PID    PROCESS  RESULT      DETAIL
42379  node     terminated

portcheck shows you what it is about to stop and who started it, then waits for your yes. It asks the process to exit cleanly before forcing it, and it refuses to stop system processes, so a mistyped port can't take down your Mac or PC.

To only look, without stopping anything:

npx portcheck-cli 3000

Install it to skip npx

brew install roystondwork-dev/tap/portcheck (macOS, Linux), npm install -g portcheck-cli or pipx install portcheck-tool (any OS), or Scoop on Windows. Then it's just portcheck kill 3000. See Install for every option.

Find your error¶

You see	Page
`Error: listen EADDRINUSE: address already in use :::3000`	Node.js, Next.js, Vite, React
`Port 5173 is in use, trying another one...`	Node.js, Next.js, Vite, React
`OSError: [Errno 48] Address already in use` (or `[Errno 98]`)	Python, Django, Flask
`Error: That port is already in use.`	Python, Django, Flask
`Port 5000 is in use by another program`	Python, Django, Flask
`Bind for 0.0.0.0:8080 failed: port is already allocated`	Docker
`Address already in use - bind(2)` / `A server is already running`	Rails, Spring Boot, Go and others
`Web server failed to start. Port 8080 was already in use.`	Rails, Spring Boot, Go and others
`listen tcp :8080: bind: address already in use`	Rails, Spring Boot, Go and others
`Only one usage of each socket address ... is normally permitted`	Windows

Or go by operating system: macOS · Windows · Linux.

Why it happens¶

Only one program can listen on a port at a time. Usually the one holding it is:

your own dev server from earlier, still running in another terminal, a closed terminal tab, or the background;
a server that crashed or was suspended (Ctrl+Z) without releasing the port;
another app that uses the same default port, such as AirPlay Receiver on port 5000 on macOS, or a database or container you forgot about.

portcheck's started by column usually tells you which one: npm ← zsh is a terminal you started, Code Helper is your editor, docker:web is a container.

Stop it happening again¶

Instead of freeing the port each time, start your app on a free port:

portcheck run --port 3000 --next -- npm run dev

This uses port 3000 if it's free and the next free port if not, and passes it to your app in $PORT. See Run on a free port. In VS Code, JetBrains IDEs, Neovim and the browser, portcheck names the holder as soon as your app hits the error.

Compared with kill-port¶

npx kill-port 3000 is the other common answer. It force-kills whatever is listening, straight away. See portcheck vs kill-port for the differences.