Claude Code on Windows:
How to Set It Up So It Actually Works

Claude Code is built for Unix-like systems (macOS and Linux). On Windows, you need WSL2. Without it, Claude Code is flying blind — it doesn’t have a proper shell to work with, so it resorts to generating .bat files and telling you to run things manually. With WSL2, it works exactly like it does on a Mac: writing code, running scripts, installing packages, executing tests, managing git — all autonomously.

This guide walks you through the full setup from scratch.

What Is WSL2 and Why Do You Need It?

WSL2 (Windows Subsystem for Linux 2) runs a real Linux kernel inside Windows. It’s not a virtual machine you have to manage — it’s a Microsoft-built feature that gives you a native Linux environment alongside your Windows desktop. It’s fast, lightweight, and free.

Claude Code’s command execution is built around bash (the standard Linux/Mac shell). PowerShell and Command Prompt don’t speak the same language. WSL2 gives Claude Code the bash environment it expects, and suddenly everything just works.

Prerequisites

• Windows 10 version 2004 or higher, or Windows 11
• Administrator access on your machine
• An Anthropic API key or Claude Pro/Max subscription

Step 1: Install WSL2

Open PowerShell as Administrator (right-click the Start button → “Terminal (Admin)” or search for PowerShell and click “Run as administrator”).

Run:

wsl --install

This installs WSL2 with Ubuntu as the default Linux distribution. When it finishes, restart your computer.

After the restart, an Ubuntu terminal window will open automatically and ask you to create a Linux username and password. This is separate from your Windows login — pick something you’ll remember, as you’ll need it for sudo commands.

Already have WSL1? Upgrade with wsl --set-default-version 2. You can check your version with wsl -l -v.

Step 2: Update the System and Install Dependencies

Open your Ubuntu terminal (search “Ubuntu” in the Start menu) and run:

sudo apt update && sudo apt upgrade -y

Then install the tools Claude Code will need:

sudo apt install -y python3 python3-pip python3-venv git curl build-essential

This gives you Python 3, pip, git, and the build tools that many packages depend on.

Step 3: Install Node.js

Claude Code requires Node.js 18 or higher. The version in Ubuntu’s default repositories is usually outdated, so install from NodeSource:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Verify the installation:

node --version
npm --version

You should see Node v22.x.x (or higher) and npm 10.x.x (or higher).

Step 4: Install Claude Code

Now install Claude Code globally:

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

Launch it for the first time:

claude

It will walk you through authentication. You’ll either connect your Anthropic API key or authenticate through your Claude subscription.

Step 5: Navigate to Your Projects

Your Windows files are accessible from inside WSL at /mnt/c/. So if your projects live in C:\Users\YourName\Documents\Projects, you can get there with:

cd /mnt/c/Users/YourName/Documents/Projects/my-project

From there, launch Claude Code:

claude

Performance tip: File operations are faster when your project lives inside the WSL filesystem (your ~ home directory) rather than on the Windows side (/mnt/c/). If you’re starting a new project, consider keeping it in ~/projects/ instead. For existing Windows-side projects, /mnt/c/ works fine — it’s just slightly slower for large file operations.

Step 6: Let Claude Code Run Autonomously

By default, Claude Code asks your permission before executing every command. This is a safety feature, but it can slow things down once you trust what it’s doing. Here are your options, from most cautious to most autonomous:

Option A: Approve Each Command (Default)

Just press y and Enter each time Claude Code wants to run something. Good for learning what it does and staying in control.

Option B: Trust for the Session

While Claude Code is running, type ! and press Enter. This approves all commands for the rest of the current session. Next time you launch Claude Code, it resets to asking permission again.

Option C: Full Autonomous Mode

Launch Claude Code with:

claude --dangerously-skip-permissions

This skips all permission prompts. Claude Code will write files, run scripts, install packages, and execute commands without asking. Use this when you’re working on a personal project and want maximum speed.

A note on the name: Yes, it literally says “dangerously” in the flag. It’s a reminder that you’re giving an AI full access to run commands on your system. For personal projects and learning, it’s fine. For production codebases or anything sensitive, stick with Option A or B.

Option D: Configure an Allowlist

You can configure specific tools and commands that Claude Code is always allowed to run without asking. Add this to your Claude Code settings (~/.claude/settings.json):

{
  "permissions": {
    "allow": [
      "Bash(python3 *)",
      "Bash(pip install *)",
      "Bash(git *)",
      "Write",
      "Edit"
    ]
  }
}

This lets Claude Code run Python, install packages, use git, and edit files without prompting — but it’ll still ask before doing anything else. You can customize this list to match your workflow.

Verify Everything Works

Here’s a quick smoke test. Open your Ubuntu terminal, launch Claude Code, and ask it:

“Create a Python script that fetches the current weather for New York from wttr.in and prints a summary. Save it and run it.”

If Claude Code is set up correctly, it will:

1. Write a Python script to a file
2. Execute it directly
3. Show you the output

No .bat files. No “please run this manually.” It just does it.

Troubleshooting

“command not found: claude”

Node.js or npm wasn’t installed correctly, or the global npm path isn’t in your $PATH. Try:

export PATH="$PATH:$(npm config get prefix)/bin"

If that works, make it permanent:

echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Claude Code still can’t run commands

Make sure you’re running Claude Code inside the WSL/Ubuntu terminal, not in PowerShell or Command Prompt. The terminal matters.

Python scripts fail with “module not found”

Install the missing module using pip inside WSL:

pip3 install module-name

If you’re working on a project with a requirements.txt:

pip3 install -r requirements.txt

Slow file access on /mnt/c/

This is a known WSL limitation — cross-filesystem I/O between Windows and Linux is slower than native Linux I/O. For large projects, clone or move them into your WSL home directory:

mkdir -p ~/projects
cp -r /mnt/c/Users/YourName/Documents/my-project ~/projects/
cd ~/projects/my-project

WSL uses too much memory

WSL2 can be memory-hungry. Create or edit C:\Users\YourName\.wslconfig:

[wsl2]
memory=4GB
processors=2

Then restart WSL:

wsl --shutdown

VS Code Integration

If you use VS Code, install the WSL extension from Microsoft. This lets you:

• Open your WSL projects directly in VS Code
• Use the integrated terminal as a WSL bash shell
• Run Claude Code from VS Code’s terminal with full Linux support

To open a WSL project in VS Code:

cd ~/projects/my-project
code .

VS Code will automatically connect to your WSL environment.

Summary

Once WSL2 is set up, Claude Code on Windows works identically to Claude Code on Mac — no compromises, no workarounds.