Claude Code WSL Installation | WSL 2 Sandbox Setup

3 Reasons to Install Claude Code on WSL

Although Claude Code now runs natively on Windows, there are clear reasons to still choose WSL source.

1. Sandbox feature is only supported on WSL 2 — for developers who want to run automated code execution in an isolated environment
2. Full Linux toolchain available — use make, gcc, python3, Docker, and more directly
3. Official Anthropic documentation translates directly — most official docs are Linux-based

Conversely, you might not want WSL if your projects are native Windows applications (.NET, UWP, MSIX distribution, etc.) and you want to avoid filesystem I/O overhead. The native Windows path is covered separately in Installing Claude on Windows.

Functional Differences Between WSL 1 and WSL 2 — Sandbox is WSL 2 Only

The official documentation summarizes the differences as follows source.

The sandbox is a feature that lets Claude Code run shell commands in an environment isolated from the host OS, and is well-suited for long-running tasks, experimental script execution, and validating untrusted code generation. If you plan to use this feature, migrating to WSL 2 should be your top priority.

Prerequisites — Switching to WSL 2 and Checking OS Requirements

Note: Using Claude Code requires a paid plan (Pro / Max / Team / Enterprise), Anthropic Console (API pay-as-you-go), Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. It cannot be launched with a Free plan alone. Confirm this now to avoid having to redo steps after installation.

First, check whether WSL 2 is installed. Run the following in PowerShell (or Windows Terminal).

wsl --list --verbose

If the VERSION column shows 2, you are ready to proceed. If it shows 1, upgrade with the following commands.

wsl --set-version Ubuntu 2
wsl --set-default-version 2

OS requirements are Windows 10 1809 or later, or Windows Server 2019 or later, with hardware requirements of x64 or ARM64 / 4 GB RAM or more source. Supported WSL distributions are Ubuntu 20.04 or later / Debian 10 or later / Alpine 3.19 or later, and Ubuntu 22.04 LTS from the Microsoft Store is a safe choice.

Quickest Method — Run install.sh in One Line Inside the WSL Terminal

Open a WSL terminal (open an Ubuntu tab in Windows Terminal or launch it directly from the Start menu) and run the following source.

curl -fsSL https://claude.ai/install.sh | bash

This is the same installer used on macOS, Linux, and WSL. It places the binary at ~/.local/bin/claude. Only this path supports automatic updates, so it is the preferred choice for ongoing use.

After installation, verify with two commands: the version display and the health check.

claude --version
claude doctor

If the claude command is not found, check the PATH configuration described below.

Authentication via Browser Login

When you launch Claude Code for the first time, a browser will open and ask you to log in to your Anthropic account. Claude Code cannot be used with the Free plan source. A Pro / Max / Team / Enterprise plan, or access via Anthropic Console (API pay-as-you-go), Amazon Bedrock, Google Vertex AI, or Microsoft Foundry is required.

claude  # First launch → log in via browser

When you launch claude inside WSL, it opens the Windows-side browser by default, so if you are already logged in to your account on the host Windows machine, you can use that session directly.

Alternative Paths — apt / dnf / apk Repositories

For cases where you want to install declaratively via scripts — such as internal distribution, Dockerfiles, or CI environments — Anthropic's official APT / DNF / APK repositories are convenient source.

Debian / Ubuntu (apt)

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Fedora / RHEL (dnf)

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Alpine (apk)

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

Automatic updates work via the repository as well, but it is easier to manage operationally by tying updates to the package manager's update cycle (apt update && apt upgrade).

WSL-Specific Pitfalls and Workarounds

Here are four common stumbling points specific to WSL.

Pitfall 1: claude: command not found

In most cases immediately after installation, the PATH has simply not been reloaded.

source ~/.bashrc
# or open a new terminal

If it still is not found, check the PATH.

echo $PATH | grep .local/bin

If it is not included, add it to .bashrc.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Pitfall 2: ripgrep Not Working on Alpine / musl

Alpine Linux uses the lightweight musl libc instead of the standard glibc (GNU C Library), which means the ripgrep bundled with Claude Code — built for glibc — does not work out of the box. Install the system-side ripgrep with apk add libgcc libstdc++ ripgrep and configure USE_BUILTIN_RIPGREP=0 to use that version instead of the bundled one source.

apk add libgcc libstdc++ ripgrep

Then add the following to ~/.claude/settings.json.

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Pitfall 3: Git for Windows Is Not Needed Inside WSL

The native Windows path uses Git Bash for Bash tools and therefore requires Git for Windows, but inside WSL it is completely unnecessary source. Simply install git on the WSL side with sudo apt install git, and Claude Code will use the WSL-side bash directly as a Bash tool. You do not need to set CLAUDE_CODE_GIT_BASH_PATH in WSL either.

Pitfall 4: Mixing Up Windows and WSL File Paths

Referencing the Windows filesystem from inside WSL (e.g., /mnt/c/Users/YourName/project) causes significantly slower file I/O. The golden rule is to keep your projects under $HOME on the WSL side (e.g., ~/projects/...) and open them with VS Code Remote-WSL or Cursor's WSL integration. Claude Code's sandbox and long-running tasks also run more stably on the WSL native filesystem.

Updating and Uninstalling

The native install version (via install.sh or apt/dnf/apk) supports automatic updates. Configuration to control this behavior is written in ~/.claude/settings.json source.

{
  "autoUpdatesChannel": "stable",
  "env": {
    "DISABLE_AUTOUPDATER": "0"
  }
}

• autoUpdatesChannel — latest (immediate new features) or stable (approximately 1 week delay, skips regressions)
• Manual update — claude update
• Disable updates — DISABLE_AUTOUPDATER=1

To fully uninstall, run the following.

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
rm -rf ~/.claude
rm -f ~/.claude.json

If you installed via apt / dnf / apk, use the respective package manager's remove command first, then delete the configuration files above.

Enabling the Sandbox

We have emphasized throughout that the sandbox is the main reason to choose WSL 2, and enabling it is a two-step process: install the dependencies and turn it on source. The sandbox is a mechanism that lets Claude Code run shell commands in isolation from the host OS. On macOS it uses the OS-native Seatbelt; on Linux / WSL 2 it uses bubblewrap (filesystem isolation) and socat (network proxying).

First, install the dependencies on the WSL 2 side.

sudo apt-get install bubblewrap socat

Next, run /sandbox inside a Claude Code session to open a panel where you can choose auto-allow (run isolated commands without confirmation) or regular permissions (confirm each time as before). To enable it globally for all projects, add the following to ~/.claude/settings.json.

{
  "sandbox": {
    "enabled": true
  }
}

By default, commands inside the sandbox can only write to the working directory, and approval is requested the first time a new network domain is accessed. To expand write destinations or allowed domains, add sandbox.filesystem.allowWrite or allowedDomains. In WSL 2, Windows binaries under /mnt/c/ such as cmd.exe cannot be called from within the sandbox; if needed, register them in excludedCommands to run them outside isolation. For detailed configuration references, see the official documentation.

Next Steps — Choosing Between IDE and Cowork

The typical setup after installing Claude Code on WSL is to call claude from VS Code Remote-WSL or Cursor's WSL integration. Once claude doctor confirms your environment is healthy, launch claude in a small repository and run /init to generate a CLAUDE.md for your project — that is the fastest way to get a feel for it.

If you want to run long-running tasks from Claude Desktop's GUI, you also have the option of installing Claude Desktop on the native Windows side (the Desktop app itself is not installed inside WSL). Since Desktop's Cowork feature runs in an isolated VM, the combination of Claude Code (WSL) + Claude Desktop (native Windows Cowork) is the most flexible configuration for Windows environments. For details, see Claude Desktop App: 5 Key Features Explained and the Claude Code Quickstart.