← Blog Mac Productivity

Address Already in Use on Mac: Find and Free the Port

By FavTray ·

Written by the team behind FavTray, a Mac developer dashboard for the menu bar. We check every app we cover against its own site, docs or a hands-on test, and each post says which.

Short answer: “Address already in use” means another process is already listening on the port your server wants. On a Mac, run lsof -nP -iTCP:3000 -sTCP:LISTEN (use your port) to see who owns it. Stop that program the normal way first (Ctrl+C in its terminal, docker stop, brew services stop) and use kill PID only for leftovers.

TL;DR

  • Find the owner (read-only): lsof -nP -iTCP:PORT -sTCP:LISTEN
  • Stop it the polite way: Ctrl+C in its terminal, docker stop, or brew services stop. Kill comes last.
  • Kill a leftover: kill PID, and kill -9 PID only if it ignores you for a few seconds.
  • Port 5000 or 7000: it’s macOS AirPlay Receiver (Apple lists both ports), not your app (port 5000 fix).
  • No Terminal: FavTray’s Ports lists every listening port in the menu bar.

The error looks different in every stack, but it’s always the same event: your server called bind() on a port, and macOS refused because something else owns it. This guide is about working out what that something is and stopping it without collateral damage. If you only want the one-liner, the kill port mac guide has it.

What does “address already in use” look like in each language?

The kernel error is EADDRINUSE, which is errno 48 on macOS (it’s 98 on Linux, which is why Stack Overflow answers show both). Node.js and Python both document it under that name. Each runtime wraps it differently:

StackWhat you see
Node.jsError: listen EADDRINUSE: address already in use :::3000
Python (sockets, uvicorn)OSError: [Errno 48] Address already in use
Django runserverError: That port is already in use.
Flask / WerkzeugAddress already in use, then Port 5000 is in use by another program. Either identify and stop that program, or start the server with a different port.
Rails (Puma)Address already in use - bind(2) for "127.0.0.1" port 3000 (Errno::EADDRINUSE)
Golisten tcp :8080: bind: address already in use
Java / Spring Bootjava.net.BindException: Address already in use, and Spring Boot adds Port 8080 was already in use.
Docker (another container)Bind for 0.0.0.0:5432 failed: port is already allocated
Docker (a Mac process)Ports are not available: exposing port TCP 0.0.0.0:5432 ... bind: address already in use

The :::3000 in the Node message is IPv6 notation for “every address, port 3000”, not a typo. Flask’s development server docs cover the same error and tell Mac users to check AirPlay Receiver when the port is 5000.

How do I find what is using the port?

Two read-only commands tell you almost everything.

  1. Find the listener. Replace 3000 with your port:

    # read-only
    lsof -nP -iTCP:3000 -sTCP:LISTEN
    COMMAND   PID  USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
    node    48213 akash   20u  IPv6 0x8c1f2a6b3e7d1a90      0t0  TCP *:3000 (LISTEN)

    The PID column is what you need. -sTCP:LISTEN (documented in the lsof manual page) matters: without it you also get every client connected to the port, including your browser. The lsof port mac cheat sheet explains every column.

  2. Find out what that PID actually is. “node” could be any of five projects:

    # read-only: full command line, parent PID and how long it's been running
    ps -o pid,ppid,etime,command -p 48213
    
    # read-only: which folder it was started from
    lsof -a -p 48213 -d cwd

    The working directory usually settles it: ~/code/shop-frontend tells you which project left a server behind.

If lsof prints nothing, skip to What if lsof shows nothing? below.

How do I stop it cleanly before killing it?

Killing works, but the owner often has a proper off switch, and using it avoids side effects like a database recovering on next start or a container restarting itself. Match the COMMAND column:

lsof showsWhat it usually isClean way to stop it
node, python3, ruby, java, your Go binaryA dev server you startedCtrl+C in its terminal tab, or kill PID (SIGTERM)
com.docker.backendA container publishing the portdocker ps --filter publish=3000, then docker stop <name>, or docker compose down in its project
postgres, redis-server, mysqldA Homebrew servicebrew services list, then brew services stop postgresql@16 (use the name it lists)
ControlCe on 5000 or 7000macOS AirPlay ReceiverTurn it off in System Settings (steps)
idea, Code Helper, java started by an IDEAn IDE run configurationStop it from the IDE’s run panel

Two of these deserve a warning. Killing com.docker.backend takes down Docker Desktop’s networking for every container, not just the one you meant. And Homebrew services run under launchd, which may start the process again a moment after you kill it, so the port comes straight back. Stop those through their own tools.

When should I kill the process, and how?

Kill it when it’s a leftover: a dev server whose terminal is gone, or one you can’t find a window for.

  1. Ask it to quit (SIGTERM). The server gets a chance to close connections and delete its pid file:

    kill 48213
  2. Check after three to five seconds. Run the lsof command again. No output means the port is free.

  3. Force it only if it’s still there (SIGKILL). This is destructive: no cleanup runs, so unsaved state is lost. Don’t do it to a database you care about.

    kill -9 48213

If kill replies Operation not permitted, the process belongs to root or another user. Put sudo in front, after checking the USER column to make sure it’s really yours to stop.

The combined find-and-kill one-liner, and versions for ports 3000, 5173 and 8080, live in the kill port 3000 mac guide. For Next.js and Rails specifics, see freeing port 3000 for Next.js and Rails.

Why is the port still busy after I closed the terminal?

Closing a Terminal tab sends SIGHUP to the shell’s jobs, and most dev servers exit on it. The ones that survive are usually one of these:

  • Started in the background with & or nohup, so the hangup never reached them.
  • Orphaned by a script runner. npm run dev that runs concurrently, a monorepo task runner, or a watcher like nodemon can crash while its child keeps serving.
  • Started by an IDE task that kept running after you closed the editor window.
  • A child that inherited the socket. A server that forks workers passes the listening socket down. Kill the parent and the child still holds the port, which is why lsof sometimes lists two PIDs on one port.

People call these “zombie” servers, but a real zombie process (state Z in ps) has already exited and holds no sockets. What holds your port is an orphan: alive, working, and adopted by launchd (PID 1) after its parent died. You can spot them:

# read-only: dev-looking processes whose parent is launchd
ps -A -o pid,ppid,etime,command | awk '$2 == 1' | grep -E 'node|python|ruby|java'

To stop a whole family at once (parent plus children), kill the process group. Find the group ID first, and note this hits every process in that group:

ps -o pgid= -p 48213      # read-only, prints the group ID, e.g. 48190
kill -- -48190            # SIGTERM to the whole group

What if lsof shows nothing?

Three causes cover nearly every case:

  1. The process isn’t yours. lsof without sudo only sees your own processes. Run sudo lsof -nP -iTCP:3000 -sTCP:LISTEN.
  2. A closed connection in TIME_WAIT. These belong to no process, so lsof can’t show them. On macOS they clear after 30 seconds (twice net.inet.tcp.msl, which is 15,000 ms). Most dev servers set SO_REUSEADDR and rebind anyway; a hand-written socket server without it has to wait. netstat -an -p tcp | grep '\.3000 ' shows them.
  3. The server crashed while starting. Your own app may bind the port twice, for example a second listen() call or a hot reloader starting a new copy before the old one exits. The second bind fails against the first. The stack trace points at your own code.

How do I stop this from happening again?

  • Quit servers with Ctrl+C, not by closing the tab. It’s the cleanest signal they get.

  • Handle SIGTERM in your own servers so kill works on the first try. In Node:

    process.on('SIGTERM', () => server.close(() => process.exit(0)));
  • Give each project its own port. PORT=3001 in one project’s .env ends most daily clashes.

  • Watch for silent port hopping. Vite and recent Next.js versions move to the next free port in development instead of failing. Handy, but it hides orphans: if your app is suddenly on 3002, you probably have two old copies running.

  • Bind Docker to loopback when the port is only for you: -p 127.0.0.1:5432:5432. By default a published port listens on every interface (Docker docs).

Is there a way to see every port without Terminal?

Apple’s built-in option: in Activity Monitor, double-click a process and open the Open Files and Ports tab. It works, but you have to know which process to inspect first, and there’s no search by port.

FavTray’s Ports does it the other way round. We make FavTray, so weigh our take accordingly. It runs lsof for you and lists every listening TCP port in the menu bar, grouped into dev servers, Python, Java, Docker, databases, web servers and system, with search by port or process name. Kill asks for confirmation first, and system ports are labelled so you don’t take out ControlCenter by mistake.

Scanning, search and filters are free with no limit. Free also includes 10 kills a day (reset at local midnight), and past that the button copies kill <pid> for Terminal. Unlimited kills are part of Pro, $4.99 once, and every install starts with a 7-day full trial with no card. If you already live in the terminal, the commands above are all you need; a dedicated menu bar list helps most when you juggle several projects a day.

Try FavTray Free

One free Mac menu bar app: notch island, ports, keep-awake, clipboard, eye rest, and Claude and Codex limits.

Download Free

Frequently Asked Questions

What does 'address already in use' mean on a Mac?

Your server asked macOS for a port that another process is already listening on, so the bind call failed with EADDRINUSE (errno 48 on macOS). Node prints 'listen EADDRINUSE', Python prints '[Errno 48] Address already in use', Go prints 'bind: address already in use'. The fix is to find the process holding the port with lsof, then stop it or pick another port.

How do I find which process is using a port on Mac?

Run 'lsof -nP -iTCP:3000 -sTCP:LISTEN' in Terminal, replacing 3000 with your port. It lists the command name, PID and user of the process listening there. It's read-only, so it's safe to run any time. If it prints nothing but the error persists, run it again with sudo, because the process may belong to root or another user.

Why is the port still in use after I closed the terminal?

The server process outlived its terminal. That happens when it was started in the background, by a script runner whose parent crashed, by an IDE task, or by a watcher like nodemon that spawned a child. Check its parent with 'ps -o ppid= -p PID'. A parent of 1 means it's an orphan adopted by launchd, and it's safe to stop with 'kill PID'.

Should I use kill -9 to free a port?

Only as a last resort. Plain 'kill PID' sends SIGTERM, which lets the server close connections, flush logs and remove pid files. 'kill -9' sends SIGKILL, which stops it instantly with no cleanup, and can leave a database or a Rails pid file in a bad state. Try SIGTERM, wait a few seconds, and only then force it.

How do I fix 'port is already allocated' in Docker on Mac?

Another container already publishes that host port. Run 'docker ps --filter publish=5432' (with your port) to find it, then 'docker stop' it or run 'docker compose down' in its project. If Docker instead says 'bind: address already in use', a Mac process holds the port: find it with lsof, or map the container to a different host port.

Something new: My Dock Buddies