Complete installation guide for Windows using Windows Subsystem for Linux (WSL). Choose your experience level to get started.
For experienced users - get Claude Code running in 4 commands
# Install WSL (if not already installed)
wsl --install
# Install Node.js in WSL
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Install Claude Code
npm install -g @anthropic-ai/claude-code
# Run Claude Code
claudeNew to WSL or command line? Follow our detailed, beginner-friendly guide with explanations for each step.
Experienced with WSL and development tools? Jump to advanced configurations and enterprise features.
Claude Code does not run natively on Windows. You must use Windows Subsystem for Linux (WSL) to create a Linux environment within Windows.
Follow these detailed steps to install Claude Code on Windows. Each step includes explanations and troubleshooting tips.
First, we need to enable WSL on your Windows system. This creates a Linux environment within Windows.
Open PowerShell or Command Prompt as Administrator and run:
wsl --installThis command will enable WSL, install Ubuntu as the default distribution, and restart your computer.
If the automatic installation doesn't work:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestartdism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestartwsl --set-default-version 2Tip: After installation, you can access WSL by typing "Ubuntu" in the Start menu or opening Windows Terminal.
Install Ubuntu as your Linux distribution. This provides the environment where Claude Code will run.
# List available distributions
wsl --list --online
# Install Ubuntu
wsl --install -d UbuntuNote: The first launch will take a few minutes as Ubuntu sets up the environment. You'll be asked to create a username and password.
Update the Ubuntu system to ensure you have the latest packages and security updates.
In your Ubuntu terminal, run these commands:
# Update package list
sudo apt update
# Upgrade installed packages
sudo apt upgrade -y
# Install essential build tools
sudo apt install build-essential curl git -ysudo apt update - Downloads the latest package informationsudo apt upgrade -y - Installs available updatesbuild-essential - Provides compilation toolscurl - Tool for downloading filesgit - Version control systemTerminal Tip: You can paste commands in WSL terminal using Ctrl+Shift+V or right-click.
Claude Code requires Node.js 18 or higher. We'll install the latest LTS version using NodeSource repository.
# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
# Install Node.js
sudo apt-get install -y nodejs
# Verify installation
node --version
npm --versionTo avoid permission issues when installing global packages:
# Create directory for global packages
mkdir -p ~/.npm-global
# Configure npm to use this directory
npm config set prefix ~/.npm-global
# Add to PATH in your shell profile
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# Reload shell configuration
source ~/.bashrc
Important: Never use sudo with npm install for global packages. This can cause permission issues and security risks.
Now we can install Claude Code using npm. This will download and install the latest version.
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code
# Verify installation
claude --version# Check if Claude Code is in PATH
which claude
# Should output something like: /home/username/.npm-global/bin/claudeSuccess! If you see a version number, Claude Code is installed correctly.
Set up authentication to use Claude Code. You can use either Claude Max subscription or an API key.
claude# Navigate to your project
cd /mnt/c/Users/YourUsername/Projects/your-project
# Start Claude Code
claude# Set API key
export ANTHROPIC_API_KEY=your_key_here
# Add to shell profile
echo 'export ANTHROPIC_API_KEY=your_key' >> ~/.bashrc
source ~/.bashrcTip: Claude Max subscription ($20/month) is more economical for regular users than pay-per-use API.
Test Claude Code with your first project and learn basic commands.
Your Windows files are accessible from WSL at /mnt/c/:
# Navigate to your Windows projects
cd /mnt/c/Users/YourUsername/Projects
# Or create a new project
mkdir claude-test
cd claude-test
# Initialize a simple project
echo "console.log('Hello Claude!');" > hello.js# Start Claude Code in your project
claude
# Try some basic commands
> "Explain what this JavaScript file does"
> "/init" # Generate project documentation
> "/help" # See all available commandsCongratulations! You've successfully installed Claude Code on Windows. You're ready to start AI-powered coding!
Quick setup for experienced developers with advanced configurations and enterprise features.
Automated installation script for experienced users. Assumes WSL2 is already configured.
# One-line installation (run in WSL)
curl -fsSL https://raw.githubusercontent.com/anthropics/claude-code/main/install.sh | bash
# Or manual quick setup
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs build-essential curl git
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
npm install -g @anthropic-ai/claude-codeOptimize WSL2 performance for better Claude Code experience.
Create %USERPROFILE%\.wslconfig:
[wsl2]
memory=8GB
processors=4
swap=2GB
localhostForwarding=true
[experimental]
sparseVhd=true
autoMemoryReclaim=gradual# Add to ~/.bashrc
export ANTHROPIC_API_KEY=your_key
export CLAUDE_MODEL=claude-sonnet-4
export MCP_DEBUG=false
export NODE_OPTIONS="--max-old-space-size=4096"
# Windows integration
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0Advanced configurations for enterprise environments and team deployments.
Create ~/.claude.json:
{
"defaultModel": "claude-sonnet-4",
"permissions": {
"allowedTools": ["Edit", "Bash(git*)"],
"deniedTools": ["Bash(rm*)"]
},
"preferences": {
"autoCompact": true,
"compactThreshold": 50000
},
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Projects"]
}
}
}# GitHub Actions workflow
name: Claude Code CI
on: [push, pull_request]
jobs:
claude-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '20'
- run: npm install -g @anthropic-ai/claude-code
- run: claude --dangerously-skip-permissions -p "review this PR"
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}Use Claude Code in containerized environments for isolation and reproducibility.
# Dockerfile for Claude Code
FROM node:20-slim
RUN apt-get update && apt-get install -y \
git \
curl \
build-essential \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /workspace
VOLUME ["/workspace"]
ENV ANTHROPIC_API_KEY=""
CMD ["claude"]# Build and run
docker build -t claude-code .
docker run -it --rm -v $(pwd):/workspace -e ANTHROPIC_API_KEY=your_key claude-code
# Or use dangerous mode for automation
docker run --rm -v $(pwd):/workspace -e ANTHROPIC_API_KEY=your_key claude-code \
claude --dangerously-skip-permissions -p "fix all linting errors"Common issues and solutions specific to Windows and WSL environments.
# Check WSL status
wsl --status
# Update WSL
wsl --update
# Restart WSL
wsl --shutdown
wsl# Check which npm is being used
which npm
which node
# Should show /usr/bin/npm, not /mnt/c/...# Fix npm permissions
sudo chown -R $(whoami) ~/.npm-global
npm config set prefix ~/.npm-globalWork within WSL filesystem, not Windows drives:
# Instead of /mnt/c/Users/...
# Use ~/projects/ or /home/username/projects/
# Copy project to WSL
cp -r /mnt/c/Users/YourName/project ~/project
cd ~/projectIncrease WSL memory allocation in .wslconfig:
[wsl2]
memory=8GB
processors=4# Reset WSL network
wsl --shutdown
# Restart WSL and try againYou've successfully installed Claude Code on Windows. Here's what to explore next:
Need help? Check our troubleshooting guide or visit the community resources.