Open the correct Jupyter URL
List running servers
jupyter server listCopy the exact URL shown. It includes the actual port, base path, and—in many local configurations—a temporary token.
Start a server if none is listed
jupyter lab # or jupyter serverKeep this terminal open so startup errors and request logs remain visible.
Test the listener
curl -I http://127.0.0.1:8888A redirect to a login or lab path is a valid server response. Connection refused is not an authentication problem.
Common symptoms
| Symptom | Likely explanation | What to do |
|---|---|---|
| Browser asks for a token | Jupyter is reachable and authentication is working as designed. | Use the tokenized URL from jupyter server list or the startup log. |
| Server opened on 8889 | 8888 was unavailable when Jupyter started. | Use the printed port, or stop the owner of 8888 after identifying it. |
ERR_CONNECTION_REFUSED | No listener at the requested address/port, or Jupyter is in another environment. | Check the server list and operating-system listener. |
| Login succeeds, then redirects incorrectly | A reverse-proxy base URL or forwarded-header setting may not match. | Compare the direct local URL with the proxied URL and inspect Jupyter logs. |
| Kernel will not start | The web server is already reachable; the failure is in the kernel environment. | Inspect kernel logs, environment, and kernelspec instead of changing port 8888. |
Choose a fixed port when needed
jupyter lab --ip=127.0.0.1 --port=8888
# Refuse to move to another port when 8888 is occupied
jupyter lab --ip=127.0.0.1 --port=8888 --port-retries=0Use a fixed port for a known local bookmark or proxy configuration. Otherwise, the port printed by Jupyter is the source of truth.
Jupyter in Docker
# Host 8888 → container 8888
docker run --rm -p 8888:8888 your-jupyter-image
# Check the mapping that Docker actually published
docker ps --format "table {{.Names}}\t{{.Ports}}"The Jupyter process in the container must listen on 0.0.0.0 for Docker’s published port to reach it. Read the container log for the tokenized URL, then use the host-side port in your browser.
Access from another computer
Jupyter’s default loopback binding is intentionally local. The official public-server guidance requires deliberate IP binding, authentication, and HTTPS considerations. For a team or multiple users, Jupyter recommends JupyterHub rather than sharing one personal server.
A Jupyter session can execute code and read files as your user. Do not expose it by disabling authentication or broadly opening 8888. Prefer SSH tunneling, a secured reverse proxy, or JupyterHub for remote use.
What if 8888 is not Jupyter?
MAMP and custom web apps can also use 8888. Identify the process rather than applying Jupyter instructions to an unrelated server:
# Windows PowerShell
Get-NetTCPConnection -LocalPort 8888 -State Listen
# macOS or Linux
lsof -nP -iTCP:8888 -sTCP:LISTENA valid HTML page from an unexpected product means the port works; the wrong process owns it.
Official references
- Jupyter Server: Running a serverStarting, listing, stopping, and authenticating local servers.
- Jupyter Server: Running a public serverDefault local binding, remote-access risks, and multi-user guidance.
- Docker: Publishing portsHow the two sides of a port mapping relate.