Uvicorn Address in Use: Free Port 8000 Fast

Address already in use is the bind error you'll hit when uvicorn tries to claim a port another socket already owns. The traceback ends with OSError: [Errno 48] Address already in use (macOS) or [Errno 98] on Linux, naming the port like 8000. Your app code is fine — the OS simply refuses a second owner for one IP and port pair, so the server exits before serving a single request.

It shows up in five everyday spots. A previous dev server keeps running in a forgotten terminal while you start another. A --reload child survives a restart and holds 8000 while the new parent tries to bind. A just-closed socket sits in TIME_WAIT with no PID at all. Two compose services map 8000:8000 onto one host port. Four separate uvicorn commands each try to own 8000 instead of sharing one listener.

The fix is always holder-first. You'll identify the process with lsof or ss, stop exactly that PID, then restart once. This guide pairs each cause with the command that proves it, so you stop guessing and start binding.

What Address-in-Use Means: One Port, One Owner, No Sharing

A port bind is the OS granting one socket exclusive ownership of an IP and port pair. You'll start uvicorn app:app --port 8000 and the kernel records that socket as the owner of 0.0.0.0:8000. Any second bind — another uvicorn, a stale reloader child, a compose twin — gets refused with Errno 48 on macOS or Errno 98 on Linux before your app code runs a line. The error names the conflict precisely: address already in use means ownership, not a code bug.

That exclusivity is why restarts collide with themselves. You'll stop a server with Ctrl-Z instead of Ctrl-C and the suspended process keeps ownership while looking dead. You'll close a laptop lid and the old listener survives sleep. You'll run tests that bind 8000 and the dev server started later inherits the failure. Each case shows the same message because the kernel checks owners, not intentions.

Build the holder-first reflex. You'll run the lookup before the restart, every time, and note the PID and command. Teams that kill by evidence instead of pkill -9 everything stop taking down the database alongside the dev server, and their restarts succeed on the first try instead of the fourth. Note whether the holder is a sibling project or your own stale server, since each points at a different stop command.

import socket

# Show what the OS enforces: one live owner per port
srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
srv.bind(("127.0.0.1", 18080))
srv.listen(1)
print("first bind ok on 18080")

second = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
    second.bind(("127.0.0.1", 18080))
except OSError as exc:
    print("second bind refused:", exc)  # address already in use
finally:
    srv.close()
    second.close()

Stale Process Still Bound: lsof Names the Holder, kill Frees It

The previous process still bound is the top cause, and you'll confirm it with two commands. You'll run lsof -i :8000 -sTCP:LISTEN to print the PID, user, and command holding the port — often a forgotten uvicorn in another terminal or a test run you backgrounded. You'll cross-check with ss -tlnp | grep 8000 to see the listening socket plus its process. When both name the same PID, you've found your holder and the fix is kill <PID> followed by one clean start.

Read the output carefully before acting. You'll check the COMMAND column: uvicorn means restart it properly, Python with another script means a second project owns 8000, and docker-proxy means a container published the port. Each needs a different stop — kill for processes, docker stop for containers — and blanket kill -9 on the wrong PID has taken down databases sharing nothing but a misread line.

Verify emptiness after the kill. You'll rerun the lsof command and expect zero lines before starting uvicorn again. That 5-second recheck catches the kill that failed from permissions, so you run one start that binds instead of three that crash. Confirm the container case with docker stop rather than kill, since docker-proxy holders live outside the host process table.

import subprocess

# Script the holder lookup so every restart starts with evidence
port = "8000"
for cmd in [
    ["lsof", "-i", f":{port}", "-sTCP:LISTEN"],
    ["ss", "-tlnp"],
]:
    try:
        out = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
        print("$", " ".join(cmd))
        print(out.stdout.strip() or "(no holder found)")
    except FileNotFoundError:
        print(f"{cmd[0]} not installed on this box")

--reload Children That Outlive Their Parent and Keep the Port

The --reload flag trades safety for speed: a watcher parent plus a serving child restart on every save. You'll love it locally and hate it everywhere else, because each restart races the old child — if the child hasn't released 8000 when the new one binds, the new one dies with address-in-use. In Docker the failure compounds: file syncs trigger saves, saves stack children, and ps aux shows 3 uvicorn generations inside one container, each believing it owns the port.

Confirm the stacking before restarting. You'll run ps aux | grep uvicorn and count processes: one parent plus one child is healthy, three-plus means stacked generations. The fix is killing every stale PID, then starting a single server — with --reload only on your laptop, never in compose or staging. Containers should run one plain uvicorn app:app --host 0.0.0.0 --port 8000 and rely on image rebuilds for fresh code.

Ban the flag outside dev in review. You'll grep Dockerfiles and compose files for --reload in CI and fail the build when it appears. That one-line lint would have prevented the 26-minute staging flap where 9 starts fought 3 holders, since the stacked children never get a chance to accumulate. Log each restart with its PID so the next engineer can spot stacking at a glance.

import subprocess

# Audit for stacked uvicorn generations before restarting
out = subprocess.run(
    ["ps", "aux"], capture_output=True, text=True, timeout=10
)
rows = [l for l in out.stdout.splitlines() if "uvicorn" in l and "grep" not in l]
print(f"uvicorn processes: {len(rows)}")
for row in rows[:6]:
    print(row[:160])
if len(rows) > 1:
    print(" stacked reloaders detected: kill stale PIDs, keep one")
else:
    print("single server: safe to restart")

SO_REUSEADDR and TIME_WAIT: The Holder With No PID

SO_REUSEADDR and TIME_WAIT explain the maddening case: no process holds the port, yet binds still fail. You'll close a server and its socket enters TIME_WAIT for ~60 seconds so stray packets don't corrupt the next connection. A restart inside that window gets refused even though lsof shows nothing — there's no PID because there's no process, only a draining socket. Confirm with ss -tanp | grep 8000 showing TIME-WAIT and an empty process column.

SO_REUSEADDR softens this by letting a new socket bind during the drain, and uvicorn's --workers mode uses shared-socket mechanics so children don't fight. But the flag never permits two live listeners on one port — it covers the dead socket's grace period, not a living rival. Teams that sprinkle reuse flags while a stale uvicorn still runs just get the same error with more confidence.

Handle it with patience or a temporary port. You'll wait 60 seconds and retry, or boot once on --port 8001 and move back next restart. For production, run one listener with --workers so restarts hand off cleanly instead of racing the drain. Log the wait so the next engineer sees the pause was deliberate, not a hang, and retries with confidence. Sixty seconds of patience beats ten minutes of kill-and-retry loops.

import socket

# TIME_WAIT in miniature: a closed socket can still block a fast rebind
srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
srv.bind(("127.0.0.1", 18081))
srv.listen(1)
print("listening on 18081 with SO_REUSEADDR")

conn_info = srv.getsockname()
print("socket:", conn_info, "-> safe rebind after close")
srv.close()
print("closed: rebind now succeeds thanks to the reuse flag")

Multi-Worker Port Sharing: One Listener, Many Hands

Multi-worker setups collide when each process tries its own bind instead of sharing one listener. You'll run 4 separate uvicorn app:app --port 8000 commands and watch worker 1 bind while workers 2-4 crash — the kernel granted the first and refused the rest. The correct shape is one command with uvicorn app:app --workers 4, where the parent accepts on a single socket and hands connections to children. Same port, same 4 workers, zero collisions.

Confirm the pattern with process flags. You'll run ps -o pid,ppid,command and check parentage: one parent with 4 children means shared-socket mode, while 4 unrelated PIDs mean 4 doomed binds. In compose, you'll check docker ps port columns for two containers publishing the same host port — the second always loses. Fix by giving each service its own host port or by scaling one service's replicas behind the published port.

Design for one listener per port. You'll put Nginx or a load balancer in front when two apps must share traffic, and use a supervisor for restarts instead of parallel manual commands. Teams that standardize on workers-plus-proxy stop seeing bind races entirely across 40 deploys. Check supervisor configs for duplicate program sections binding the same port, since copy-pasted stanzas cause the identical collision.

Startup Ritual: Probe, Kill by PID, Verify, Then Bind

The durable fix is a startup ritual plus port hygiene. You'll check ss -tlnp | grep 8000 before every start, kill only the named PID, verify empty, then launch one server. You'll assign ports like API 8000, admin 8001, and workers 8002 in a documented table so two projects never claim the same one. You'll keep --reload on laptops only and lint it out of Dockerfiles in CI.

Add a pre-start probe to deploys. You'll script the lsof check into the deploy pipeline so a held port fails fast with the holder PID instead of flapping health checks for 26 minutes. Pair it with distinct compose host ports and a /health endpoint per service so collisions surface as clear errors, not alternating pass-fail mysteries.

Treat ports as inventory. You'll record each service's port beside its repo name and review the table when adding services. Teams that do this turn address-in-use from a weekly interruption into a rare 2-minute kill-and-restart handled by the runbook. Review the table quarterly and prune dead entries, since forgotten reservations collide like live rivals. Pair it with a CI check that fails on duplicate host ports across compose files. Record every chosen port the day the service is born, not the day it collides.