How to change the Jupyter Notebook port

Jupyter Notebook starts a local web server before the browser interface can open. The default listener normally uses port 8888, which can conflict with another Notebook session, a reserved development port, or a local forwarding rule.

Notebook 7 is served by Jupyter Server, so persistent listener settings belong in jupyter_server_config.py as ServerApp traits. Setting c.ServerApp.port changes the port used by future Notebook starts from that config file, and the Notebook config display confirms which file and value are active.

Changing the port does not make Notebook remotely reachable by itself. Keep c.ServerApp.ip on localhost for local-only access, use c.ServerApp.port_retries = 0 when the selected port must be exact, and treat tokenized startup URLs as secrets.

1. Check the active Jupyter config directory.

   $ jupyter --config-dir
   /home/user/.jupyter

2. Generate the Jupyter Server config file if it does not already exist.

   $ jupyter server --generate-config
   Writing default config to: '/home/user/.jupyter/jupyter_server_config.py'

   If jupyter_server_config.py already exists, save a backup before overwriting a file that contains custom settings.

   Related: How to generate a Jupyter Notebook configuration file

3. Open the Jupyter Server config file.

   $ vi ~/.jupyter/jupyter_server_config.py

4. Add the Notebook listener settings.

   c.ServerApp.ip = "127.0.0.1"
   c.ServerApp.open_browser = False
   c.ServerApp.port = 8899
   c.ServerApp.port_retries = 0

   Use a free port that fits your local convention. port_retries = 0 makes Jupyter fail instead of silently moving to a nearby port when 8899 is already in use.

5. Confirm Notebook reads the configured port.

   $ jupyter notebook --show-config
   Loaded config files:
     /home/user/.jupyter/jupyter_server_config.py
   ServerApp
     .ip = '127.0.0.1'
     .open_browser = False
     .port = 8899
     .port_retries = 0

   Command-line flags override the config file. Remove older launcher, shortcut, or service-unit flags such as --port=8888 when they should no longer win.

6. Start Jupyter Notebook without opening a browser automatically.

   $ jupyter notebook --no-browser
   [I ServerApp] Serving notebooks from local directory: /home/user/notebooks
   [I ServerApp] Jupyter Server 2.20.0 is running at:
   [I ServerApp] http://127.0.0.1:8899/tree?token=<token>
           http://127.0.0.1:8899/tree?token=<token>
   ##### snipped #####

   The token in the startup URL grants access to the running Notebook session. Do not paste a real token URL into shared tickets, screenshots, or logs.

7. List the running Jupyter server.

   $ jupyter server list
   Currently running servers:
   http://127.0.0.1:8899/?token=<token> :: /home/user/notebooks

   The listed URL should show the configured port. Another server may still use 8888 separately, so match the directory or runtime record before stopping anything.

   Related: How to find a Jupyter Notebook login token

8. Check the login page on the new port.

   $ curl --include --silent --show-error http://127.0.0.1:8899/login
   HTTP/1.1 200 OK
   Server: TornadoServer/6.5.7
   Content-Type: text/html; charset=UTF-8
   X-Content-Type-Options: nosniff
   Content-Security-Policy: frame-ancestors 'self'; report-uri /api/security/csp-report
   ##### snipped #####

9. Stop the test server when the port check is complete.

   $ jupyter server stop 8899
   [JupyterServerStopApp] Shutting down server on 8899...

   Related: How to stop a running Jupyter Server