How to Install WSL2 + Ubuntu on Windows for AI Development (2026 Guide)

If you’ve tried installing AI development tools like Claude Code, NanoClaw, or other cutting-edge AI CLIs on Windows, you’ve probably hit the same wall: “Linux or macOS only.” The fastest way to install WSL2 Ubuntu for AI development is through Windows Subsystem for Linux 2 (WSL2), which gives you a full Linux environment running natively inside Windows — no dual boot, no virtual machine overhead, no compromises.

This guide walks you through every step, from enabling WSL2 to running your first AI tool. This guide takes about 30-45 minutes to complete. By the end, you’ll have a fully configured Ubuntu development environment with Node.js, Python, Docker, and Claude Code ready to go.

What Is WSL2 and Why Does It Matter for AI Development?

WSL2 (Windows Subsystem for Linux 2) is Microsoft’s technology that lets you run a real Linux kernel directly on Windows. Unlike WSL1, which translated Linux system calls into Windows calls, WSL2 runs an actual Linux kernel in a lightweight virtual machine managed by Windows. This architectural shift has major implications:

• Full system call compatibility — every Linux binary works, including Docker containers and complex AI toolchains
• Near-native performance — file system operations within the Linux filesystem are dramatically faster than WSL1
• GPU passthrough — NVIDIA CUDA and AMD ROCm work for machine learning training and inference
• Seamless integration — access Windows files from Linux and vice versa, share network ports, and even launch Windows applications from the Linux command line
• Low resource overhead — WSL2 uses a fraction of the resources a traditional VM would require, with fast startup times measured in seconds

For AI development specifically, WSL2 matters because the entire AI/ML ecosystem is built around Unix. Most AI frameworks (PyTorch, TensorFlow, Hugging Face Transformers, JAX), package managers (pip, conda, poetry), containerization tools (Docker, Podman), and modern AI CLI tools like Claude Code assume a Unix-like environment. Without WSL2, Windows developers face constant compatibility issues, broken build scripts, and tools that simply refuse to install. At AI Tools Hub, we use WSL2 daily to test and review every tool we cover — it’s the foundation of our workflow.

WSL1 vs WSL2: Which Should You Use?

If you’re wondering whether WSL1 might be sufficient, the short answer for AI development is: always use WSL2. Here’s a quick comparison:

Feature	WSL1	WSL2
Linux Kernel	Translation layer (no real kernel)	Full Linux kernel
Docker Support	Not supported	Full Docker support
GPU Access (CUDA/ROCm)	Not supported	Full GPU passthrough
Linux Filesystem Speed	Slower	Near-native speed
Windows Filesystem Access	Faster (direct)	Slower (crosses VM boundary)
System Call Compatibility	Limited	100% compatible
Memory Usage	Lower	Higher (but configurable)

WSL1 only wins on cross-filesystem access speed, which is a minor concern if you store your projects in the Linux filesystem (which you should — more on that later). For anything involving Docker, GPU computing, or modern AI tools, WSL2 is the only viable option.

Prerequisites to Install WSL2 Ubuntu for AI Development

Before you start, make sure your system meets these requirements:

Requirement	Details
Windows Version	Windows 10 version 2004 (Build 19041) or higher, or Windows 11
RAM	8 GB minimum (16 GB recommended for AI workloads)
Disk Space	At least 20 GB free (Ubuntu + Docker images add up fast)
CPU	64-bit processor with virtualization support (Intel VT-x or AMD-V)
BIOS	Hardware virtualization must be enabled (usually under “Advanced” or “CPU Configuration”)

To check your Windows version, press Win + R, type winver, and press Enter. You’ll see your build number in the dialog that appears.

Step 1: Enable and Install WSL2

Microsoft has simplified WSL2 installation significantly. A single command handles everything: enabling the WSL feature, enabling the Virtual Machine Platform, downloading the Linux kernel, and installing Ubuntu.

Open PowerShell as Administrator

Right-click the Start button and select “Terminal (Admin)” or search for “PowerShell”, right-click it, and choose “Run as administrator”.

Run the Install Command

wsl --install

Expected output:

Installing: Virtual Machine Platform
Virtual Machine Platform has been installed.
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.
Installing: Ubuntu
Ubuntu has been installed.
The requested operation is successful. Changes will not be effective until the system is restarted.

Restart your computer when prompted. This is required — the kernel components won’t load until you reboot.

If the Command Shows Help Text Instead

If you already have WSL installed but without a distribution, the wsl --install command may just display help text. In that case, install Ubuntu explicitly:

wsl --install -d Ubuntu-24.04

You can see all available distributions with:

wsl --list --online

If the install process hangs at 0.0%, try downloading the distribution first:

wsl --install --web-download -d Ubuntu-24.04

Enable BIOS Virtualization (If Needed)

If you get an error about virtualization not being enabled, you’ll need to enter your BIOS/UEFI settings:

1. Restart your computer and press F2, F10, Del, or Esc during boot (varies by manufacturer)
2. Navigate to Advanced > CPU Configuration
3. Enable Intel Virtualization Technology (VT-x) or AMD-V / SVM Mode
4. Save and exit (usually F10)

Common BIOS key by manufacturer: Dell (F2), HP (F10), Lenovo (F1 or Enter), ASUS/Acer (F2 or Del).

Step 2: Install Ubuntu 24.04 LTS

After restarting, Ubuntu should launch automatically and prompt you to create a user account. If it doesn’t, open it from the Start menu or run:

wsl

Why Ubuntu 24.04 LTS?

Ubuntu 24.04 LTS (Noble Numbat) is the recommended distribution for AI development in 2026. It ships with Python 3.12, has long-term security support until 2029, and is the target platform for all major AI/ML frameworks. Ubuntu 26.04 LTS is expected in April 2026 with even better AMD ROCm GPU support, but 24.04 remains the stable, battle-tested choice today.

Create Your Linux User

You’ll see a prompt like this:

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: yourname
New password:
Retype new password:
passwd: password updated successfully
Installation successful!

Choose a username and password. This is your Linux account — it’s separate from your Windows login. You’ll need this password for sudo commands.

Verify WSL2 Is Running

Open a new PowerShell window and run:

wsl --list --verbose

Expected output:

  NAME            STATE           VERSION
* Ubuntu-24.04    Running         2

The VERSION column should show 2. If it shows 1, upgrade it:

wsl --set-version Ubuntu-24.04 2

Step 3: Initial Ubuntu Setup — Update Everything

Your first task inside Ubuntu is to update all packages. Open your Ubuntu terminal and run:

sudo apt update && sudo apt upgrade -y

Expected output (abbreviated):

Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Get:2 http://archive.ubuntu.com/ubuntu noble-updates InRelease [126 kB]
...
Reading package lists... Done
Building dependency tree... Done
Calculating upgrade... Done
The following packages will be upgraded:
...
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

Then install essential build tools that many packages depend on:

sudo apt install -y build-essential curl wget unzip software-properties-common ca-certificates gnupg

Step 4: Install Essential AI Development Tools

Now let’s install the core tools you’ll need for AI development: Node.js, Python, Git, and GitHub CLI.

Install Node.js 22 LTS (via nvm)

Using nvm (Node Version Manager) is the recommended approach — it installs Node.js in your home directory, avoiding permission issues that plague global installs. This is particularly important because AI CLI tools like Claude Code are installed via npm.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Reload your shell configuration:

source ~/.bashrc

Install Node.js 22 LTS (the current active LTS as of March 2026 — supported until April 2027):

nvm install 22
nvm use 22
nvm alias default 22

Verify the installation:

node --version
npm --version

Expected output:

v22.x.x
10.x.x

Install Python 3 and pip

Ubuntu 24.04 comes with Python 3.12 pre-installed, but you’ll want pip and venv for managing AI packages:

sudo apt install -y python3-pip python3-venv python3-dev

Verify:

python3 --version
pip3 --version

Expected output:

Python 3.12.x
pip 24.x from /usr/lib/python3/dist-packages/pip (python 3.12)

Pro tip: Always use virtual environments for Python AI projects to avoid dependency conflicts. This is especially important because AI libraries like PyTorch and TensorFlow have complex dependency chains that can conflict with each other:

python3 -m venv ~/ai-env
source ~/ai-env/bin/activate

Install Git and Configure It

Git comes pre-installed on Ubuntu, but let’s make sure it’s up to date and configured:

sudo apt install -y git
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
git config --global init.defaultBranch main

Install GitHub CLI

GitHub CLI (gh) is essential for modern development workflows — pull requests, issue management, and authentication all from the terminal:

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install -y gh

Authenticate with GitHub:

gh auth login

Follow the interactive prompts — select GitHub.com, HTTPS protocol, and authenticate via browser. Your credentials will be stored securely and used by both gh and git.

Step 5: Install Docker Desktop with WSL2 Integration

Docker is essential for AI development — many AI tools, models, and services run in containers. Docker Desktop’s WSL2 backend provides significantly better performance than the older Hyper-V backend, and it’s the officially recommended way to run Docker on Windows.

Install Docker Desktop on Windows

1. Download Docker Desktop from docker.com/products/docker-desktop
2. Run the installer and ensure “Use WSL 2 based engine” is checked during setup
3. Restart your computer if prompted

Enable WSL2 Integration

1. Open Docker Desktop
2. Go to Settings > General
3. Confirm “Use the WSL 2 based engine” is checked
4. Go to Settings > Resources > WSL Integration
5. Toggle on your Ubuntu distribution
6. Click Apply & Restart

Storage note: Docker Desktop stores container data at C:\Users\[USERNAME]\AppData\Local\Docker\wsl by default. If your C: drive is low on space, change this location under Settings > Resources > Advanced before pulling large AI model images.

Verify Docker in WSL2

Open your Ubuntu terminal and run:

docker --version
docker run hello-world

Expected output:

Docker version 27.x.x, build xxxxxxx

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

If you get a permission error, make sure Docker Desktop is running on Windows and that WSL Integration is enabled for your Ubuntu distro.

Also verify Docker Compose is available:

docker compose version

Expected output:

Docker Compose version v2.x.x

Important: Uninstall Any Conflicting Docker Installs

If you previously installed Docker Engine directly inside WSL, remove it first to avoid conflicts with Docker Desktop. Running both simultaneously causes unpredictable errors:

sudo apt remove docker docker-engine docker.io containerd runc 2>/dev/null

Step 6: Install Claude Code CLI in WSL2

Claude Code is Anthropic’s agentic coding tool that runs in your terminal. It understands your codebase, executes commands, edits files, and handles complex development workflows through natural language. It requires a Unix-like environment, which is exactly what WSL2 provides.

Install Claude Code via npm

npm install -g @anthropic-ai/claude-code

Important: Never use sudo with npm install -g. Since we installed Node.js through nvm, global packages install to your home directory without needing root permissions. If you get EACCES permission errors, it means you’re not using nvm — go back to the Node.js step and install via nvm.

Verify the installation:

claude --version

Authenticate Claude Code

Run Claude Code for the first time to authenticate:

claude

This will open a browser window on your Windows side for authentication. Log in with your Anthropic account (you’ll need a Claude Pro or API subscription), and the CLI will store your credentials automatically.

Quick Test

Navigate to any project directory and try a simple command:

cd ~/
mkdir test-project && cd test-project
git init
claude "Create a simple Python script that prints Hello World"

If Claude Code responds and creates the file, your setup is working perfectly.

Step 7: Verify Your Complete AI Development Environment

Let’s run a comprehensive check to make sure everything is installed and working. Run this verification script in your Ubuntu terminal:

echo "=== WSL2 AI Development Environment Check ==="
echo ""
echo "--- System ---"
uname -a
echo ""
echo "--- Node.js ---"
node --version
echo ""
echo "--- npm ---"
npm --version
echo ""
echo "--- Python ---"
python3 --version
echo ""
echo "--- pip ---"
pip3 --version
echo ""
echo "--- Git ---"
git --version
echo ""
echo "--- GitHub CLI ---"
gh --version
echo ""
echo "--- Docker ---"
docker --version
echo ""
echo "--- Docker Compose ---"
docker compose version
echo ""
echo "--- Claude Code ---"
claude --version 2>/dev/null || echo "Claude Code: not installed or not authenticated"
echo ""
echo "=== All checks complete ==="

Expected output should show version numbers for each tool. If any command fails, revisit the corresponding step above.

Optimize WSL2 Performance for AI Workloads

The default WSL2 configuration is fine for general development, but AI workloads benefit from some tuning. Create or edit %UserProfile%\.wslconfig on the Windows side with these recommended settings:

[wsl2]
memory=12GB
swap=8GB
processors=6

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true

Key settings explained:

• memory — set this to 75% of your total RAM for AI training workloads; the default 50% can be restrictive for large models
• swap — generous swap space helps when loading large AI models that temporarily exceed RAM
• autoMemoryReclaim — releases unused memory back to Windows gradually (available since WSL 1.3.10)
• sparseVhd — reclaims disk space automatically when files are deleted inside WSL

Apply changes by shutting down WSL from PowerShell:

wsl --shutdown

Then relaunch your Ubuntu terminal.

Common Issues and Troubleshooting When Installing WSL2 Ubuntu

Even with the streamlined setup, you may encounter some issues. Here are the most common ones and their fixes.

WSL2 Uses Too Much Memory

By default, WSL2 can consume up to 50% of your system RAM. If you notice Windows becoming sluggish, limit WSL2’s memory usage via the .wslconfig file described in the optimization section above, then restart WSL:

wsl --shutdown

VPN Breaks WSL2 Networking

Corporate VPNs often interfere with WSL2’s virtual network adapter. This is one of the most common issues developers face. Common fixes:

1. Update WSL — newer versions handle VPN adapters better:

   wsl --update

2. Set DNS manually inside WSL if name resolution fails:

   sudo rm /etc/resolv.conf
   echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
   sudo chattr +i /etc/resolv.conf

3. Try mirrored networking mode (Windows 11 22H2+) — this makes WSL2 share the host’s network stack directly, which solves most VPN issues:

   [wsl2]
   networkingMode=mirrored

   Add this to your .wslconfig and restart WSL.

“WslRegisterDistribution failed with error: 0x80370102”

This means hardware virtualization is not enabled. Enter your BIOS settings and enable VT-x (Intel) or SVM Mode (AMD). See the BIOS section in Step 1.

Docker Commands Don’t Work in WSL

Check these in order:

1. Is Docker Desktop running on the Windows side? (Check the system tray)
2. Is WSL2 integration enabled for your distro? (Settings > Resources > WSL Integration)
3. Did you uninstall any standalone Docker Engine from inside WSL?
4. Try restarting Docker Desktop and then restart WSL: wsl --shutdown

Slow File Performance

Accessing Windows files from WSL2 (via /mnt/c/) is slow because it crosses a 9P filesystem bridge between the VM and the host. Store your projects inside the Linux filesystem for best performance:

# Good: fast native Linux filesystem
~/projects/my-ai-app/

# Slow: accessing Windows drive from WSL
/mnt/c/Users/you/projects/my-ai-app/

You can access your Linux files from Windows File Explorer by navigating to \\wsl$\Ubuntu-24.04\home\yourname.

WSL2 Fails to Start After Windows Update

Occasionally a Windows update can break WSL. Fix it by updating the WSL kernel:

wsl --update
wsl --shutdown
wsl

“npm ERR! EACCES: permission denied” During Claude Code Install

This happens when Node.js was installed via apt instead of nvm. The fix is to install nvm and use it to manage Node.js:

sudo apt remove nodejs npm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22

Then retry npm install -g @anthropic-ai/claude-code — no sudo needed.

What’s Next? Start Building with AI Tools

Congratulations — you now have a production-ready AI development environment running on Windows. Here’s what you can do next:

• Set up NanoClaw — our guide on installing and configuring NanoClaw for local AI agent orchestration is coming soon
• Install Python AI libraries — set up PyTorch, Transformers, and LangChain in a virtual environment:

  python3 -m venv ~/ai-dev
  source ~/ai-dev/bin/activate
  pip install torch transformers langchain openai

• Configure VS Code with WSL — install the WSL extension for VS Code to edit Linux files seamlessly from Windows:

  code .

  This single command opens VS Code on Windows connected to your WSL2 filesystem — you get the Windows GUI with Linux filesystem performance.

• Set up GPU passthrough — if you have an NVIDIA GPU, install the CUDA toolkit inside WSL2 for ML training:

  sudo apt install -y nvidia-cuda-toolkit

• Explore more AI CLI tools — browse our tutorials and reviews for the latest AI development tools that run on Linux

Your WSL2 + Ubuntu environment is the same environment used in production servers, CI/CD pipelines, and cloud instances worldwide. Any AI tool or framework that works on Linux now works on your Windows machine with full performance. No more “Linux only” roadblocks — you’re ready to build.