## 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.

```text
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/pst_JWsDtxTctSJ2lm_uVrvLMw