How to enable GPU in WSL2 for ML and CUDA step by step

If you work with machine learning, deep learning, or data science On Windows, you've probably wondered more than once whether it's worth setting up a separate Linux distribution or using the cloud. With official GPU support in WSL2, there's no need to complicate things: you can have a real Linux environment accelerated by CUDA directly on your Windows PC.

In this guide we will see, step by step, How to enable GPU support in WSL2 for ML and CUDAWhat you need at the system level, how to install the correct drivers, how to prepare Ubuntu (or another distro), how to integrate CUDA, cuDNN, Docker, TensorFlow, PyTorch and DirectML, and how to solve the most typical problems you will encounter along the way.

Architecture: how the GPU works within WSL2

WSL2 runs a real Linux kernel inside a lightweight virtual machine which is managed by Windows itself. It's not a shoddy emulation: it's real Linux, with its kernel and user space, but extremely integrated with the host system.

To take advantage of the GPU from within that kernel, NVIDIA (and Microsoft) have developed a A specific stack that exposes the Windows host GPU to WSL2From the Linux perspective, what appears is the classic CUDA interface via libcuda.soThis allows the software to think it is running on a “native” Linux system.

Thanks to that layer, within WSL2 you can use nvidia-smi, nvcc, CUDA Toolkit, cuDNN and virtually any CUDA-compatible ML framework (PyTorch, TensorFlow, etc.) without needing to set up a heavy virtual machine or always depend on the cloud.

Furthermore, this integration extends to Docker and NVIDIA Container ToolkitSo you can run GPU-enabled containers just like you would on a dedicated Linux server: for example, official NVIDIA NGC images for TensorFlow, PyTorch, or other AI frameworks.

In terms of graphics, WSLg also lets you control which GPU is used for Linux graphical applications, which is very useful if your computer has a Intel iGPU or AMD integrated GPU and a dedicated NVIDIA graphics card And you want the heavy lifting to go to NVIDIA.

Windows requirements, GPU and required versions

For all of this to work, the first filter is the operating system: you need Windows 11 or Windows 10 version 21H2 or laterPrevious versions do not have mature (or simply do not have) GPU support in WSL2.

At the hardware level, a Modern GPU with updated driversFor pure CUDA you will need a compatible NVIDIA GPU (ideally a recent RTX series), but you can also rely on DirectML if your GPU is AMD or Intel, or even if you prefer to use frameworks adapted to DirectML on an NVIDIA.

Additionally, WSL2 must run a sufficiently recent kernel. For GPU features, a kernel version 5.10.43.3 or higherYou can check this from PowerShell with:

wsl cat /proc/version

If you're setting up the environment from scratch on an updated Windows system, you'll most likely already have a compatible version, but it's worth checking in case your computer hasn't received updates in a while or if you've manually changed the WSL settings.

Install and update WSL2 with a suitable Linux distribution

Before getting into drivers and CUDA, you need to make sure that WSL2 is installed and configured correctlyFor ML development, it is recommended to use a glibc-based distribution, such as Ubuntu or Debian, due to its compatibility with NVIDIA repositories and packages.

From PowerShell with administrator privileges, you can enable WSL and the necessary component for WSL2 using the appropriate Windows commands. In modern versions of Windows 10/11, the most direct approach is to use wsl -install and specify the distribution, for example:

wsl –install -d Ubuntu-22.04

Once the installation is complete, you'll see the new Ubuntu app in the Start menu. The first time you open it, you'll be prompted to complete the basic setup (username, password, etc.). The next essential step is update the package cache and the system within that distro:

sudo apt update && sudo apt -y upgrade

Additionally, it's advisable to ensure that WSL itself is using the latest kernel available for Windows. From PowerShell, run:

wsl-update

This combination of steps leaves you with a Ubuntu updated on WSL2, perfect as a base for CUDA installations, ML frameworks or even Docker.

Installing the NVIDIA driver with CUDA support for WSL2

The critical part for using a GPU with CUDA in WSL2 is the NVIDIA driver installed on WindowsNot within Linux. Many people get confused thinking they also need to install the driver within the distro, but for WSL2 it's not necessary.

You must download the CUDA and WSL enabled controller From NVIDIA's official WSL page (or from the general driver search, selecting your GPU and system). It's important not to stick with an outdated driver: WSL2 and GPU support has received substantial improvements.

Once the driver is installed on Windows, you can verify that the system correctly recognizes the GPU and driver using PowerShell. Run a command that displays adapter information, or simply open the NVIDIA Control Panel and check the version. From WSL, when everything is working correctly, nvidia-ks It will return the list of available CUDA devices.

In server scenarios (e.g., Windows Server with WSL2), the flow is similar: first you install WSL and the Linux distro, and then the NVIDIA driver for Windows ServerNext, on the Linux side, you only install the CUDA Toolkit and the necessary libraries, without any additional GPU drivers within the WSL kernel.

Installing CUDA Toolkit, cuDNN, and base tools within WSL2

With WSL and the NVIDIA driver ready, it's time to configure the development environment within Linux. The goal is to have the following installed: CUDA Toolkit, cuDNN, and basic Python tools to be able to compile, run examples and work comfortably with ML frameworks.

There are two approaches: using the official NVIDIA repositories for WSL/Ubuntu Or you can use the nvidia-cuda-toolkit package from your distribution. For modern workflows, it's best to add the NVIDIA repositories specific to your distribution, as these are usually more up-to-date than generic packages.

From your Ubuntu terminal in WSL2, you can add the repositories and then install CUDA. An alternative, simpler approach in some environments is:

sudo apt -y install python3-pip nvidia-cuda-toolkit

If you use this package, make sure the CUDA version it installs is compatible with the PyTorch or TensorFlow versions you plan to use. Once installed, it's a good idea to include the path to the CUDA binaries in your PATH variable, for example, by editing the file ~/.bashrc and adding a line like this:

export PATH=/home/user/.local/bin${PATH:+:${PATH}}

After saving and closing, simply open a new terminal session or run source ~/.bashrc for the changes to take effect. From there you can use tools like nvcc or run example scripts that use CUDA.

Using Docker and NVIDIA Container Toolkit in WSL2

In many ML workflows, especially in large enterprises or projects, it's common to encapsulate everything in containers. To leverage the GPU from Docker within WSL2, you need the The Docker engine has access to the GPU through the NVIDIA Container Toolkit.

There are two main options: install Docker Desktop on Windows and use its integration with WSL2, or directly install the Docker engine on the Linux distribution within WSL. In the second case, you can do it with:

curl https://get.docker.com | sh
sudo service docker start

Once Docker is installed, it's time to configure the stable NVIDIA Container Toolkit repository. For Ubuntu within WSL, you can follow the typical sequence: define the distribution variable starting from /etc/os-release, add the GPG key, and the list of NVIDIA repositories for nvidia-docker.

Then you install the necessary package with:

sudo apt-get update
sudo apt-get install -y nvidia-docker2

With this up and running, you can launch containers that see the GPU using the option –gpusFor example, for an official TensorFlow container on NGC:

docker run –gpus all -it –shm-size=1g –ulimit memlock=-1 –ulimit stack=67108864 nvcr.io/nvidia/tensorflow:20.03-tf2-py3

Within that container, many examples are already prepared. For example, you can go to NVIDIA's CNN examples and run a pre-trained ResNet:

cd nvidia-examples/cnn/python
resnet.py –batch_size=64

In server environments with multiple GPUs, you can also try sample containers like the classic nbody CUDA to verify that all cards are responding correctly via Docker:

docker run –rm -it –gpus=all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark -numdevices=5

TensorFlow, PyTorch and DirectML in WSL2

WSL2 is not limited to pure CUDA: it also allows you to take advantage of TensorFlow-DirectML and PyTorch-DirectMLThis is especially interesting if your GPU is AMD or Intel, or if you want to take advantage of DirectML even with an NVIDIA card.

The starting point is the same: updated driver from the GPU vendor Installed on Windows, whether AMD, Intel, or NVIDIA. From there, you create a virtual Python environment within your Linux distribution. A common option is to use Miniconda:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
conda create –name directml python=3.7 -y
conda activate directml

With the environment activated, you install the framework you're interested in. TensorFlow-DirectML:

pip install tensorflow-directml

Y for PyTorch-DirectMLFirst, you cover some basic BLAS and LAPACK dependencies, and then you install the corresponding package:

sudo apt install liblas3 libomp5 liblapack3
pip install torch-directml

To verify that everything is working, you can open a Python session and try a simple operation (for example, a tensor sum) and check that no errors occur and that DirectML acceleration is detected in the framework's output.

Installing PyTorch with CUDA support in WSL2

If your goal is to use PyTorch with "traditional" CUDA on an NVIDIA GPU, the easiest way is to install the version specifically designed for a particular CUDA version, for example, CUDA 11.8PyTorch provides specific indexes for compatible wheels.

Once you have Python and pip or a Conda environment ready, you can run something like:

pip3 install torch torchvision torchaudio –index-url https://download.pytorch.org/whl/cu118

To verify that PyTorch correctly sees the GPU, enter the interactive Python console within WSL2 and run:

import torch
torch.cuda.device_count()
torch.cuda.is_available()

The first command imports PyTorch, the second tells you how many CUDA-compatible devices the system detects, and the third returns a True If the GPU is available for the framework. If something goes wrong, the usual steps are to check the drivers, CUDA version, and whether WSL is up to date.

In multi-GPU environments, PyTorch also allows you to restrict usage to certain cards using environment variables such as CUDA_VISIBLE_DEVICES or device selection-specific APIs, which is useful when you share the equipment with more processes or users.

TensorFlow with CUDA on WSL2 and full ML flow

TensorFlow can also leverage the GPU in WSL2 via CUDA, especially when combined with NVIDIA Docker images or carefully curated installations from the CUDA and cuDNN repositories. The typical flow includes:

1) Install the NVIDIA driver with CUDA support on WindowsAs we have already mentioned, this ensures that the version is compatible with the TensorFlow release you are going to use.
2) Configure in WSL2 the CUDA Toolkit and cuDNN following the official NVIDIA CUDA guide in WSL.
3) Optionally, use an NGC image of TensorFlow with GPU support, which already comes adjusted with the correct CUDA/cuDNN versions, avoiding library compatibility issues.

Once your environment recognizes the GPU (you can check this with nvidia-ks (since WSL2), you can train intensive models directly from Linux on Windows, without full virtual machines or the need to upload everything to the cloud. It's common to combine this with VS Code Remote – WSL and Jupyter for working comfortably on notebooks.

For beginners, a good way to gain confidence is to try simple examples of neural networks, monitoring consumption in nvidia-ks and experiment with batch size, number of layers, or precision (FP16/FP32) to see how the GPU load varies.

GPU access verification and monitoring

Verifying that everything is configured correctly is key before starting to train large models. Since WSL2, the star command is nvidia-kswhich should show the list of GPUs, total and used memory, process consuming GPU, temperature, etc.

If the command returns a message like “No devices were found”, it is usually an indication that The Windows driver is not installed correctly or WSL is not up to dateIn many cases, it can be solved with:

wsl –shutdown

and reopening the distribution to reload the environment, or updating drivers and restarting the system. There are also additional tools such as gpustat which provide a more user-friendly summary of GPU load.

During long training sessions, it's advisable to leave a separate console with nvidia-smi or monitoring scripts for monitor temperature, memory usage and usageThis helps detect bottlenecks (e.g., running low on VRAM) or performance issues due to poor configuration.

GPU selection in systems with multiple graphics cards (NVIDIA, AMD, iGPU)

Modern laptops and desktops often have multiple GPUs: for example, one Intel iGPU or integrated AMD chip and a dedicated NVIDIA graphics cardSince WSL2, especially with WSLg for graphical apps, it's important to be able to choose which one to use.

Microsoft documents mechanisms for selecting the GPU in WSLg, and users who encountered situations where their application was using the iGPU have resolved the issue by following the official guide. GPU selection in WSLg available in the microsoft/wslg GitHub repository.

Additionally, for environments where DirectML is supported on multiple GPUs, a specific device can be selected using the environment variable:

export MESA_D3D12_DEFAULT_ADAPTER_NAME=» »

This variable performs a string match with the adapter names, so if you put something like "NVIDIA"It will select the first GPU whose name begins with NVIDIA. This is a useful trick when the system defaults to the wrong GPU (for example, prioritizing an integrated AMD GPU over a dedicated NVIDIA GPU for certain ML workloads).

In particularly troublesome cases (for example, when using FAISS or other components within frameworks like LangChain or Ollama), you might see it connect to the wrong GPU even when NVIDIA is visible in WSL. In these situations, you usually need to combine WSLg's configuration, the aforementioned environment variable, and specific library settings to force the correct device.

Best practices and solving common problems

Once everything is up and running, there are some good practices that make a difference in comfort and day-to-day performance. The first is to always work with Python virtual environments or conda, and activate them before launching any training:

source ~/.venvs/ml/bin/activate (or the equivalent command in your configuration)

Keep a file requirements.txt updated with key dependencies (for example, using pip freeze > requirements.txt) makes it easy to rebuild the environment on another machine or after formatting without headaches.

Another important recommendation is to avoid working directly on /mnt/c/ For training data or large projects, disk performance is usually much better if you use the Linux home directory in WSL (for example, ~/projects_ml), especially when you work with many files or large volumes of data.

For interactive development, VS Code with Remote – WSL extension and Jupyter support It offers a very convenient experience: you edit on Windows, run it on Linux with a GPU, and everything is quite integrated. Furthermore, you can use tools like tmux or screen to... training runs in the background even if you close the terminal window.

If you share the machine or have heavy processes running in parallel, you might want to adjust resource limits in the file .wslconfig of Windows (for example, RAM and number of cores that WSL2 can use), and manually control when you launch heavy workouts so as not to crash the computer.

Regarding troubleshooting, the most typical faults include that nvidia-smi does not detect the GPU (incorrect driver or outdated WSL), incompatibilities between CUDA versions and frameworks (PyTorch/TensorFlow), and CUDA installations directly from the web without following the official WSL repositories and guides, which often result in library conflicts. In general, it's better to rely on the WSL-specific repositories and documentation than on generic installations.

With all these elements properly configured—a modern Windows 11 or 10, updated WSL2, correct GPU drivers, CUDA/cuDNN in the distro, Docker and/or DirectML as applicable—you can have a High-performance Linux environment for AI and ML without sacrificing the convenience of Windows. It's a very powerful hybrid solution that, when properly tuned, allows you to train complex models, prototype workflows, and debug code quickly without relying heavily on cumbersome virtual machines or the cloud.