venv, installing tensorflow and notebook, and registering that environment as a Jupyter kernel with ipykernel. TensorFlow dropped native Windows GPU support after version 2.10, so running TensorFlow inside WSL 2 is the official, actively supported path for both CPU and NVIDIA CUDA workloads on Windows without dual-booting.
Prerequisites and compatibility
Before installing WSL 2 and TensorFlow, confirm that your Windows build, CPU virtualization settings, and Python version target meet current requirements:
- Supported Windows versions: Windows 11 (all editions) and Windows 10 version 2004 (Build 19041) or later support the single-command
wsl --installsetup. PressWin + R, typewinver, and pressEnterto verify your OS build. - Hardware virtualization: WSL 2 requires hardware-assisted virtualization (Intel VT-x or AMD-V) with Second Level Address Translation (SLAT) enabled in your PC's UEFI/BIOS. Open Task Manager (
Ctrl + Shift + Esc), select the Performance tab, click CPU, and confirm that Virtualization reads Enabled. - Python compatibility: TensorFlow 2.21 requires Python 3.10 through 3.13 (Python 3.14 is not yet officially supported). Ubuntu 24.04 LTS ships with Python 3.12 by default, which works out of the box.
- NVIDIA GPU support (optional): If you have an NVIDIA GPU and want CUDA acceleration, install the latest NVIDIA Windows Game Ready or Studio driver on Windows. Do not install any Linux NVIDIA display driver inside Ubuntu on WSL 2, as NVIDIA's WSL architecture forwards GPU calls from
/dev/dxgto the Windows host driver. - Storage and memory: Reserve at least 10–15 GB of free disk space for Ubuntu, Python packages, and TensorFlow wheels, plus at least 8 GB of system RAM (16 GB recommended for model training).
If Task Manager shows Virtualization: Disabled, reboot into UEFI/BIOS to enable it before continuing:
- Windows 11: Open Settings > System > Recovery, click Restart now next to Advanced startup, then choose Troubleshoot > Advanced options > UEFI Firmware Settings > Restart.
- Windows 10: Open Settings > Update & Security > Recovery, click Restart now under Advanced startup, then navigate to Troubleshoot > Advanced options > UEFI Firmware Settings > Restart.
Warning: Only change the CPU virtualization setting (often labeled Intel Virtualization Technology, VT-x, SVM Mode, or AMD-V) inside UEFI/BIOS. Modifying unrelated boot or storage settings can prevent Windows from starting.
Install Ubuntu in WSL 2
Microsoft's wsl --install command enables the Windows Subsystem for Linux and Virtual Machine Platform optional features, installs the WSL 2 Linux kernel, sets WSL 2 as the default architecture, and downloads Ubuntu.
- Open an elevated terminal on Windows:
- Windows 11: Right-click the Start button and select Terminal (Admin) (or PowerShell (Admin)).
- Windows 10: Press
Win + Xand select Windows PowerShell (Admin).
- Run the installation command:
wsl --install -d Ubuntu
- Restart your computer when prompted so Windows can finish enabling the Virtual Machine Platform.
- After signing back into Windows, Ubuntu launches automatically to finish decompressing (if it does not open on its own, open Ubuntu from the Start menu).
- When prompted, enter a Linux username and password. Typing your password produces no characters on screen; this blind typing is normal.
- Verify in PowerShell or Windows Terminal that Ubuntu is running on WSL 2:
wsl --list --verbose
Confirm that the VERSION column next to Ubuntu reads 2. If it reads 1, convert it with wsl --set-version Ubuntu 2.
- Back in the Ubuntu terminal, update the package index and upgrade existing system packages:
sudo apt update && sudo apt upgrade -y
Create an isolated Python virtual environment
Installing TensorFlow and Jupyter inside a dedicated venv environment prevents dependency conflicts with Ubuntu's system Python packages. Store your project inside the Linux filesystem (~/) rather than under /mnt/c/, because cross-OS filesystem access in WSL 2 is noticeably slower for Python imports and dataset reads.
- Install
python3-venvandpython3-pipin Ubuntu (Ubuntu separates thevenvmodule from the basepython3package):
sudo apt install -y python3-venv python3-pip
- Check your Ubuntu Python version to confirm it falls within TensorFlow's supported 3.10–3.13 range:
python3 --version
- Create a project directory in your Linux home folder and navigate into it:
mkdir -p ~/tf-jupyter && cd ~/tf-jupyter
- Create and activate the virtual environment:
python3 -m venv .venv
source .venv/bin/activate
Your shell prompt now begins with (.venv), indicating that python and pip point to the isolated environment.
- Upgrade
pipinside the virtual environment so wheel resolution and dependency checks run cleanly:
python -m pip install --upgrade pip
Install TensorFlow and Jupyter Notebook
With (.venv) active, install either the standard CPU build or the CUDA-enabled GPU build of TensorFlow, followed by Jupyter Notebook and ipykernel.
- Install TensorFlow using the command that matches your hardware:
- CPU-only installation (works on any PC):
pip install tensorflow
- NVIDIA GPU installation (installs TensorFlow along with compatible CUDA and cuDNN user-space libraries inside the virtual environment):
pip install 'tensorflow[and-cuda]'
Warning: Never runapt install nvidia-driver-*or install a Linux GPU driver package inside WSL 2. Doing so overwrites the Windows driver stubs mounted at/usr/lib/wsl/lib/and breaks GPU passthrough.
- Install Jupyter Notebook and the IPython kernel package in the same virtual environment:
pip install notebook ipykernel
- Register the virtual environment as a named Jupyter kernel so notebooks always execute against your TensorFlow environment rather than a global Python interpreter:
python -m ipykernel install --user --name=tf-wsl --display-name="Python (TensorFlow WSL)"
- Confirm that Jupyter sees the new kernel:
jupyter kernelspec list
You should see tf-wsl listed alongside the path to ~/.local/share/jupyter/kernels/tf-wsl.
Launch Jupyter, select the kernel, and test TensorFlow
WSL 2 forwards localhost ports automatically to Windows, allowing you to run the Jupyter server inside Ubuntu and interact with it from Edge, Chrome, or Firefox on Windows.
- From your
~/tf-jupyterdirectory with(.venv)active, start Jupyter without trying to launch a Linux text browser:
jupyter notebook --no-browser
- Look at the terminal output for the line starting with
localhost:8888/tree?token=(the port increments to8889if8888is already in use). - Hold
Ctrland click that URL in Windows Terminal, or copy the fulllocalhost:8888/tree?token=...address and paste it into your Windows web browser. - In the Jupyter dashboard, click New in the upper-right area and select Python (TensorFlow WSL) to open a new notebook bound to your virtual environment.
- If you open an existing
.ipynbfile instead, verify the active kernel name in the top-right corner of the notebook, or switch it via Kernel > Change Kernel > Python (TensorFlow WSL).
- If you open an existing
- Paste the following verification code into the first notebook cell and press
Shift + Enterto run it:
import tensorflow as tf
print("TensorFlow version:", tf.__version__)
print("GPUs detected:", tf.config.list_physical_devices("GPU"))
print("Tensor test:", tf.reduce_sum(tf.random.normal([1000, 1000])).numpy())
- Check the cell output:
- TensorFlow version prints your installed 2.x release.
- GPUs detected lists your NVIDIA GPU device (
PhysicalDevice(name='/physical_device:GPU:0', device_type='GPU')) if you installedtensorflow[and-cuda], or an empty list[]for CPU-only setups. - Tensor test prints a floating-point scalar sum without raising
ModuleNotFoundError.
- When you finish working, save the notebook (
Ctrl + S), return to the Ubuntu terminal, and pressCtrl + Ctwice (or typeywhen prompted) to shut down the Jupyter server cleanly.
Alternate method: Use VS Code with the WSL extension
If you prefer not to copy localhost token URLs into a browser each time you start a session, Visual Studio Code can render notebooks natively while running Python inside WSL 2.
- Install Visual Studio Code on Windows, then install the WSL extension (
ms-vscode-remote.remote-wsl) from the Extensions view (Ctrl + Shift + X). - In your Ubuntu terminal inside
~/tf-jupyter, launch VS Code connected to WSL:
code .
- Inside the WSL-connected VS Code window, install the Python and Jupyter extensions into the WSL target when prompted.
- Create or open a
.ipynbfile, click Select Kernel in the upper-right corner of the editor, choose Python Environments..., and select.venv (Python 3.12.x).
Troubleshooting and rollback
ERROR: Could not find a version that satisfies the requirement tensorflow: Your Ubuntu Python version is either older than 3.10 or newer than 3.13 (such as Python 3.14). Runpython3 --versionto check; if needed, install a supported Python release (for example Python 3.12) and recreate.venvwithpython3.12 -m venv .venv.The virtual environment was not created successfully because ensurepip is not available: Install the missing Debian/Ubuntu venv package withsudo apt update && sudo apt install -y python3-venv, delete the incomplete.venvfolder (rm -rf .venv), and runpython3 -m venv .venvagain.- Browser shows a "Password or token" prompt or refuses to connect: Confirm the Jupyter server is still running in your Ubuntu terminal—closing the terminal stops the server. Copy the complete
localhost:8888/?token=...string from the terminal, or runjupyter server listin a second Ubuntu tab while(.venv)is active to print the active URL and token. ModuleNotFoundError: No module named 'tensorflow'inside a notebook: Jupyter is running a different kernel (often the system Python). Click Kernel > Change Kernel > Python (TensorFlow WSL). If that option is missing, activate.venvin Ubuntu and re-runpython -m ipykernel install --user --name=tf-wsl --display-name="Python (TensorFlow WSL)".- NVIDIA GPU returns
[]or prints NUMA warnings: Harmless NUMA node messages on WSL 2 can be ignored ifGPU:0appears in the output. Iflist_physical_devices("GPU")returns[], runnvidia-smiinside Ubuntu. Ifnvidia-smifails, update your NVIDIA Windows driver on the Windows host, then restart WSL from PowerShell withwsl --shutdownand reopen Ubuntu. - Rollback and cleanup:
- To remove only the Jupyter kernel registration and Python environment, run:
jupyter kernelspec uninstall tf-wsl -y
deactivate
rm -rf ~/tf-jupyter
- To remove the Ubuntu WSL 2 distribution completely (which deletes all Linux files inside Ubuntu), run
wsl --unregister Ubuntufrom PowerShell.