How to Set Up WSL for AI Coding Agents on Windows

For AI coding agents on a Windows laptop, the right setup is Windows 11 with WSL 2 and an Ubuntu distro. Run the agent, editor, Git, and shell inside WSL, and keep the repo on the Linux filesystem instead of mixing Windows and Linux paths. That avoids the slow file access, permission oddities, and path confusion that usually cause trouble. Windows 10 can work on recent builds, but Windows 11 is the cleanest path. Before you start, confirm that virtualization is enabled, install WSL 2, verify the distro starts normally, and then put your code, SSH keys, and Git config inside WSL so the tools all see the same environment.

What you need before you start

• Windows 11 is the cleanest path for this setup. Recent Windows 10 versions can work too, but Windows 11 usually gives you the least friction.
• You need administrator access on the machine so you can install WSL and turn on Windows features if they are missing.
• Hardware virtualization has to be available and enabled in firmware. If it is off, WSL 2 will not work correctly.
• Plan for a few gigabytes of free disk space for the distro, updates, packages, and your repos.
• A Microsoft account is helpful for installing from the Store if you use that route, but the built-in WSL install path usually does not depend on it.
• If this is a work laptop, make sure device policy does not block virtualization, the Microsoft Store, or developer tools.

Check virtualization before you install anything else. Open Task Manager, go to the Performance tab, and look for the virtualization line. If it says disabled, turn it on in BIOS or UEFI first, then reboot and check again.

WSL 2 depends on virtualization and the Windows features that support it. If either one is missing, the rest of the setup will be unstable or fail outright.

Install WSL the easy way

Use the built-in WSL install command from an elevated PowerShell window. On a standard Windows 11 setup, this is the simplest supported path.

1. Open PowerShell as Administrator.
2. Run the WSL install command.

wsl --install

3. Restart when Windows asks you to.
4. After the reboot, let Windows finish installing the Linux components.
5. Open PowerShell again and verify that WSL is installed.

wsl --status

You should see that WSL is installed and that WSL 2 is the default version or available to use. If wsl --install tells you that some optional features are missing, let Windows add them and reboot again. If the command is not recognized, your Windows build is likely too old for the simple path and you may need to update Windows first.

If virtualization is disabled in firmware, WSL 2 may install but not run correctly. Fix that before you keep going.

If you want to confirm the Windows side too, check that the required optional features are turned on after the install. The exact message varies, but wsl --status should show a healthy WSL setup rather than an error about missing platform support.

Pick the right Linux distro for coding agents

Ubuntu is the safest default for AI coding agents. It has broad support, familiar package names, and the fewest surprises when you install developer tools. If you are following agent docs, editor docs, or shell scripts, they usually assume Ubuntu-style commands first.

A different distro can make sense if you already know you need it. For example, you might choose Debian for a very plain base, or another distribution if your team standardizes on it. For most developers on Windows, though, Ubuntu is the best starting point.

If Windows does not offer you a choice during wsl --install, you can still install Ubuntu later from the Microsoft Store or by using wsl --install -d Ubuntu.

Keep the distro choice simple. The agent does not care which logo you picked. It cares that package installs, shells, Git, Python, Node, and SSH behave predictably inside Linux.

Set up your first Linux user and update the system

After the distro launches for the first time, WSL will ask you to create a Linux username and password. Pick a normal non-root username you will remember. This account is what your tools and agent will use inside Linux.

1. Launch the distro from the Start menu or by typing wsl in PowerShell.
2. Create your Linux user when prompted.
3. Set a password when prompted.
4. Open the Linux shell and update the package lists.

sudo apt update

5. Upgrade the installed packages.

sudo apt upgrade -y

That gives you a clean base before you install anything else. If the upgrade asks to restart services, accept the prompt. If a kernel or distro update is available later, apply it before you start depending on the environment for real work.

Put your code inside WSL, not on C:\ drive

For AI coding agents, the safest place for code is the Linux filesystem inside WSL, not a folder on C:\ mounted from Windows. That avoids slow file operations and path translation issues that show up when Linux tools constantly reach into the Windows side.

Use a path like this:

/home/yourname/projects/my-agent-repo

That path lives inside WSL, so Git, shells, Python, Node, and editors connected through WSL all see the same files the same way.

If you keep the repo in something like C:\Users\you\Desktop\repo, Linux tools can still reach it through /mnt/c/..., but that setup is where many agents start feeling sluggish or flaky. The Windows filesystem is fine for documents and downloads. For code you want an agent to modify repeatedly, keep it in Linux storage.

A good habit is to create one projects folder in your Linux home directory and keep all agent-driven repos there.

Do not keep switching the same repo between Windows tools and WSL tools while you are setting this up. That is a fast way to get confused file paths, conflicting line endings, and broken assumptions about permissions.

Install the tools your agent will actually use

Most coding agents expect a basic Linux developer toolchain. You do not need a huge stack to start. Install the common pieces first, then add language-specific tools as your project needs them.

1. Install Git, curl, Python, Node tooling helpers, and build basics.

sudo apt install -y git curl build-essential python3 python3-pip nodejs npm

2. Check that Git is available.

git --version

3. Check Python.

python3 --version

4. Check Node.

node --version

5. Check npm.

npm --version

If your agent needs a more recent Node or Python than the distro provides, install that later with the method your project expects, such as a version manager. For a first setup, though, the distro packages are enough to prove the environment works.

If you use a shell-based agent, make sure you can also run ordinary commands like ls, cat, grep, and python3 from the same terminal session. The goal is a normal Linux shell, not a half-Windows, half-Linux mix.

Connect VS Code or your editor the right way

Open the project from inside WSL, not from a Windows-only workflow. That keeps the editor, terminal, and agent pointed at the same Linux filesystem.

In VS Code, the usual pattern is to open the folder from the WSL shell. If code is available in your WSL session, you can do this:

cd ~/projects/my-agent-repo
code .

That should open the folder in a WSL-connected window, with a Linux terminal behind it. If your editor has a remote or WSL extension, use that mode for the repo.

The common mistake is opening the Windows copy of the folder and then running commands in WSL against /mnt/c/.... That split setup is where agents get confused: the editor saves one copy, the shell edits another, and file watching gets noisy.

If the editor says it is connected to Windows instead of WSL, close that window and reopen the project from the WSL side. You want one environment, not two overlapping ones.

Move SSH keys and Git settings into WSL

Keep Git identity and SSH access inside WSL so cloning, pulling, and pushing work normally from the same Linux environment your agent uses.

1. Set your Git name and email inside WSL.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

2. If you sign commits, configure that in WSL too, not only in Windows.
3. Create or copy your SSH key inside WSL.
4. Add the public key to your Git host.
5. Test the SSH connection from the WSL shell.

ssh -T git@github.com

Use the SSH agent that runs in Linux, and keep your private key file in your WSL home directory with normal Linux permissions. That way the agent, Git, and your shell all use the same credentials.

A common mistake is storing keys in the Windows profile and trying to reuse them from WSL through /mnt/c/Users/.... That can work in some cases, but it often leads to permission warnings or tooling that refuses to use the key. It is cleaner to keep the key in Linux and treat Windows as the host, not the working environment.

Check that everything is really working

Before you trust the setup for a real project, run a short test inside WSL.

1. Create a fresh test folder in your Linux home directory.
2. Clone a small repo or initialize a new Git repo there.
3. Run a simple shell command from the repo root.

pwd

4. Open the folder from the WSL shell in your editor.

code .

5. Make a tiny file change, then check Git status.

git status

If the path from pwd looks like /home/yourname/..., the editor opens the same folder, and Git sees your change without complaints, the setup is working the way an AI coding agent expects.

You can also run a simple Python or Node command from the same terminal to confirm the language tools are reachable. The point is not to test everything. It is to prove that one Linux shell, one editor window, and one repo all agree on the same files.

When WSL setup goes sideways

The most common problems are predictable, and most come from mixing Windows and Linux in the wrong place.

If WSL is slow, check where the repo lives. Projects under /mnt/c/... are usually the reason. Move the code into /home/yourname/projects/... and try again.

If you see permission problems with keys or files, inspect where the files live and how they were created. Windows-owned files brought into Linux can behave differently from files created inside WSL.

If the distro will not start, confirm virtualization is enabled in firmware and that the required Windows features are on. A reboot is often part of the fix.

If the editor opens the wrong environment, you probably launched it from Windows instead of from the WSL session. Open the folder from the Linux shell so the editor attaches to WSL.

If package installs fail, update the distro first and make sure your network or proxy policy is not blocking the Linux side. WSL uses the Windows network, but some enterprise setups still interfere with package downloads.

Do not keep switching the same repo between Windows tools and WSL tools while you are setting this up. That is a fast way to get confused file paths, conflicting line endings, and broken assumptions about permissions.

Conclusion

Once WSL 2, Ubuntu, your tools, and your repo all live on the Linux side, AI coding agents behave much more predictably. Keep new projects under your WSL home directory, run Git and SSH from Linux, and open the folder through a WSL-aware editor session. If you later need more languages or services, add them one at a time inside WSL so the environment stays consistent.

Frequently Asked Questions

Can I use WSL 1 for AI coding agents?

WSL 2 is the better choice. It gives you a real Linux kernel and usually avoids the file and tool behavior that trips up coding agents.

Do I need Ubuntu specifically?

No, but Ubuntu is the safest default because most setup instructions and packages fit it well. If your team uses another distro, follow that standard instead.

Can I keep my repo on the Windows desktop and still use WSL?

You can, but it is a common source of slow operations and path confusion. For agent work, keep the repo inside the Linux filesystem.

Should Git run in Windows or WSL?

For this setup, use Git inside WSL. That keeps the editor, shell, SSH keys, and repo all in one environment.