How to Install WSL on Windows

Step-by-step setup

1. Open PowerShell as administrator

Click Start, search for PowerShell, right-click it, and choose Run as administrator. This matters because enabling WSL is a system-level Windows feature the first time you install it.

Run:

wsl --install

This installs WSL and, by default, Ubuntu. If Windows asks you to restart, restart before continuing.

2. Open Ubuntu

After the restart, open Ubuntu from the Start menu. The first launch can take a little longer because Windows is unpacking the Linux distribution.

Create a Linux username and password when prompted. This password is for Linux sudo commands inside Ubuntu. It does not need to match your Windows password.

Success looks like this: you see a Linux shell prompt, usually ending with a $, and you can type Linux commands.

3. Update Ubuntu packages

Inside Ubuntu, run:

sudo apt update

Then install a few common tools that many developer and AI setup guides expect:

sudo apt install -y curl git ca-certificates

Success looks like this: apt finishes without a blocking error, and these commands return version information:

curl --version
git --version

4. Confirm WSL 2 is active

Back in PowerShell, run:

wsl --list --verbose

You should see your distribution, such as Ubuntu, with VERSION set to 2.

If it shows WSL 1, set WSL 2 as the default for new installs:

wsl --set-default-version 2

Then convert Ubuntu if needed:

wsl --set-version Ubuntu 2

Replace Ubuntu with the exact distribution name shown by wsl --list --verbose.

5. Update WSL itself

Run this in PowerShell:

wsl --update

Then check status:

wsl --status

Microsoft lists these commands in its basic WSL command reference. You do not need every WSL command on day one, but --list --verbose, --status, --update, and --shutdown are worth knowing.

6. Start WSL in the right place

To open your default Linux distribution from PowerShell, run:

wsl

To open it directly in your Linux home directory, run:

wsl ~

For most projects, keep Linux-heavy files inside the WSL filesystem under your Linux home folder, such as:

~/projects

Avoid running large Linux package installs or container-heavy projects directly from mounted Windows paths unless a guide specifically tells you to. The Linux filesystem path is usually cleaner for developer tooling.

Verify it works

Run these checks in PowerShell:

wsl --version
wsl --status
wsl --list --verbose

Run these checks inside Ubuntu:

uname -a
pwd
sudo apt update
curl --version
git --version

WSL is ready when:

• Ubuntu opens from the Start menu
• wsl --list --verbose shows your distribution
• the distribution uses WSL 2
• sudo apt update works inside Ubuntu
• curl and git are available

That is enough for most local AI guides that tell you to run Linux commands inside WSL2.

Common problems

wsl --install only shows help text

This can happen when WSL is already installed or Windows needs a more explicit distro command. List available distributions:

wsl --list --online

Then install Ubuntu explicitly:

wsl --install -d Ubuntu

The install hangs or the Store download fails

Try the web-download option:

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

If that still fails, use Microsoft's manual install guide, especially on older Windows builds or locked-down work machines.

WSL 2 is not available

Check your Windows version and build with winver. WSL 2 requires a supported Windows version, and Microsoft notes that older builds need updates before WSL 2 works.

Also check virtualization. In Task Manager, open Performance, choose CPU, and look for the virtualization status. If it is disabled, enable Intel VT-x, Intel Virtualization Technology, AMD-V, or SVM in BIOS or UEFI.

Ubuntu opens as root or the wrong user

If your default user changed, use the distribution launcher command from PowerShell. For Ubuntu, the pattern is:

ubuntu config --default-user <Username>

Replace <Username> with the Linux user you created. If you are not sure which distributions are installed, run:

wsl --list

Networking or localhost feels confusing

When a service runs inside WSL, Windows and WSL often share local networking well, but not every tool behaves the same. Test from the environment that will actually run the command.

For example, if Hermes Agent runs inside WSL and Ollama runs on Windows, test the Ollama endpoint from inside WSL before saving it:

curl http://127.0.0.1:11434/v1/models
curl http://host.docker.internal:11434/v1/models

Use the endpoint that responds from the same shell where your tool runs.

You need to restart WSL without rebooting Windows

Run this in PowerShell:

wsl --shutdown

Then open Ubuntu again. This is useful after config changes, networking issues, or tool installs that expect a fresh WSL session.

Next useful actions

Install Docker Desktop if your next guide uses containers. Docker's Windows path uses WSL 2 for the common Linux-container workflow, so WSL is the right foundation.

Install Hermes Agent inside WSL if you want the more stable Windows path for Hermes. Use the Linux/macOS/WSL2 installer from the Hermes guide rather than the native Windows beta path unless you specifically want to test native Windows.

Install local AI tools deliberately. Ollama can run on Windows or inside WSL, but the model endpoint must be reachable from the tool that uses it. Test networking before adding web UIs, gateways, or automations.

Create a simple project folder:

mkdir -p ~/projects
cd ~/projects

Use that folder for Linux-first guides, scripts, and container projects.

Background, planning, and caveats

What WSL is

WSL stands for Windows Subsystem for Linux. It lets Windows run Linux distributions such as Ubuntu, Debian, or others without a separate dual-boot setup.

For Useful Atlas guides, WSL matters because many AI and automation tools are easiest to install in a Linux shell. It gives Windows users a clean place to run Bash commands, package installs, local services, and developer workflows without translating every step into PowerShell.

WSL 1 vs WSL 2

Use WSL 2 unless a specific legacy workflow tells you otherwise. WSL 2 is the normal choice for Docker Desktop, many Linux tools, and local AI setup because it uses a lightweight virtualized Linux environment.

You can check the version with:

wsl --list --verbose

If a guide says WSL2, it means the VERSION column should show 2.

Which Linux distribution should you choose?

Ubuntu is the default and the best first choice for most readers because documentation, package examples, and troubleshooting answers usually assume Ubuntu or Debian-style commands.

If you know you need Debian, openSUSE, Arch, or another distribution, list available options:

wsl --list --online

Then install the one you want:

wsl --install -d <DistroName>

For a first local AI setup, use Ubuntu and move on.

Security notes

WSL is part of your Windows machine. Do not treat it as a disposable cloud sandbox unless you intentionally created it that way. Commands inside WSL can access mounted Windows files, and tools you install may store credentials in your Linux home folder.

Use normal user accounts, avoid running everything with sudo, and keep API keys out of screenshots, public logs, and shared prompts. If a tool asks for broad file or terminal access, test it in a low-risk project folder first.

When to use the official docs

Use Microsoft's WSL install guide when the one-command install changes, the basic WSL command reference when you forget a command, and the WSL development environment guide when you want a deeper setup with Git, VS Code, databases, GPU acceleration, or advanced workflows.

Red flags

• You are on an old Windows build and keep retrying wsl --install instead of updating Windows or using the manual path.
• Virtualization is disabled in BIOS or UEFI.
• wsl --list --verbose shows WSL 1 when your guide requires WSL 2.
• You install Linux tools into mounted Windows folders without understanding the path difference.
• You run AI agents or scripts with broad access before testing them in a low-risk folder.
• You delete or unregister a distribution without exporting or backing up important files.

Bottom line

For most Windows users, WSL setup is simple: run wsl --install in administrator PowerShell, restart if asked, open Ubuntu, update packages, and confirm WSL 2 with wsl --list --verbose.

Once that works, Windows is ready for Linux-first local AI and tooling guides such as Docker Desktop with WSL integration, Hermes Agent inside WSL, local automation workflows, and developer commands that assume Bash.