Skip to main content

Using Jupyter in WSL

If you are already accustomed to installing Python, conda, and project dependencies in WSL, running Jupyter in WSL as well is usually more convenient. This avoids:

  • Installing separate environments on both Windows and WSL
  • Notebook opens, but the actual execution kernel is not the environment you expect
  • Files are in WSL, but you access them from the Windows environment through a detour

This document does not repeat Jupyter's complete configuration, but focuses only on the most common access methods in WSL.

Most Common Usage Pattern​

The most common and least troublesome pattern is actually:

  1. Start Jupyter in WSL
  2. Open it in a Windows browser via localhost

In many cases, you don't even need to do any additional SSH or firewall configuration.

1. Starting Jupyter in WSL​

If Jupyter is already installed in your environment, you can start it directly:

jupyter lab --no-browser --ip=0.0.0.0 --port=8888

If you prefer Notebook:

jupyter notebook --no-browser --ip=0.0.0.0 --port=8888

There are two key points here:

  • --no-browser: Prevents WSL from trying to open a graphical browser in the Linux environment
  • --ip=0.0.0.0: Makes the service listen on all network interfaces, reducing access issues caused by address binding

After startup, the terminal usually prints an access URL containing a token.

2. Accessing from Windows Browser​

WSL2 has mature support for Windows host access to Linux services, so in many scenarios you can directly open:

http://localhost:8888

to access the Jupyter you just started in WSL.

If the terminal output a complete link with a token, prefer copying that address directly to your Windows browser.

3. If You Use VS Code Remote​

If you are already connecting to WSL through VS Code Remote, another very reliable approach is to use port forwarding directly, instead of manually copying the token link.

You can refer to:

This is especially convenient for the following scenarios:

  • You have multiple Notebook or Lab ports open simultaneously
  • You don't want to manually copy the token link every time
  • You are already working in a VS Code Remote environment

4. When to Go Back to the General Jupyter Documentation​

If your problem is not "how to access from WSL," but rather more general configuration issues like:

  • How to set a password
  • How to write jupyter_server_config.py
  • How to run in the background
  • How to specify the default directory

Then see:

This WSL document is only responsible for clarifying the "start in WSL, access from Windows side" layer.

Minimal Troubleshooting Order​

If the browser cannot open the page, check in this order:

  1. In WSL: jupyter lab --no-browser --ip=0.0.0.0 --port=8888
  2. In WSL: ss -lntp | grep 8888
  3. In Windows browser: access http://localhost:8888
  4. If using VS Code Remote, check the port forwarding panel
  5. If there's a port conflict, try a different port

Common way to change the port:

jupyter lab --no-browser --ip=0.0.0.0 --port=9999

Frequently Asked Questions​

1. Browser Opens the Page, But the Execution Environment Is Wrong​

This is usually not a WSL networking issue, but rather the shell environment where you started Jupyter is not the Python environment you think it is. First confirm whether you started Jupyter inside the target virtual environment.

2. Why Not Open the Browser Directly in WSL​

Most people's WSL is primarily a terminal environment. Keeping the browser on the Windows side and Jupyter on the WSL side makes the division of labor clearer.

3. Can I Let Other LAN Machines Access This Jupyter​

Yes, but that is no longer a "WSL local access" issue -- it is a "exposing WSL service to Windows and even the LAN" issue. The approach is the same as SSH, requiring additional consideration of forwarding and security surface exposure. Unless you have a clear need, it is not recommended to expose the Notebook directly to the LAN.

Further Reading​