ZMQError: Address already in use on port 8888, jupyter failed to start

TL;DR

Something is already listening on port 8888, usually a forgotten Jupyter server in another terminal or a stale process that survived a closed laptop lid. Run jupyter notebook list (or jupyter server list) to see running servers, stop the one you do not need, or just start the new one with --port=8889. The error is informational, not corruption.

zmq.error.ZMQError: Address already in use

Use this when

• Starting Jupyter fails immediately with ZMQError address already in use on port 8888.
• You have multiple terminals, tmux sessions, or IDEs that may have started servers.
• The server died uncleanly and may have left a stale process.

Not for this skill when

• The error is Errno 99. That is a bad bind address, not a taken port.
• The server starts but kernels cannot connect. That is a kernel networking issue.

Steps

1. List running servers: jupyter server list (or jupyter notebook list on older installs). Verify: you see the process holding 8888.
2. If it is yours and unwanted, stop it: jupyter server stop 8888 or kill the PID. Verify: the list no longer shows it.
3. If you cannot find it, check the port directly: lsof -i :8888 or ss -ltnp | grep 8888. Verify: you have the PID and process name.
4. Simplest path: start on another port with jupyter lab --port=8889. Verify: the new server prints its URL with the new port.
5. If the holder is a stale process with no terminal, kill it and also clear its leftover runtime files. Verify: port 8888 is free again.

Variant phrasings

address already in use port 8888 jupyter

Short form. Another server owns the port.

jupyter port 8888 already in use

Common phrasing. List servers, stop or switch ports.

zmqerror jupyter startup

Library-level phrasing. The ZMQ socket bind is what fails.

Compatibility: All Jupyter versions. Port handling is identical in notebook 6/7 and JupyterLab.

Why it happens

Jupyter's server binds a ZeroMQ-based set of sockets starting at the configured port. Only one process can hold a port, so a second server fails fast with ZMQError. This is overwhelmingly caused by a server the user forgot about: another terminal, a VS Code session, or a process that survived a laptop sleep and kept its port.

Edge cases / pitfalls

• Killing the wrong server kills someone else's running kernels on shared machines. Check the process owner and start time first.
• A server started by an IDE may restart itself when you kill it. Stop it from the IDE instead.
• The --port flag only sets the first tried port; with --port-retries Jupyter auto-increments. Setting retries to 0 makes the failure loud and clear.
• Stale browser tabs pointing at the old server will show confusing state after you switch ports. Close or refresh them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstJWsDtxTctSJ2lmuVrvLMw