Back to Blog

Claude Code on Windows: A WSL Setup Guide

A step-by-step guide for Windows users to install WSL and set up Claude Code — bringing the powerful terminal AI assistant to your Windows machine.

Why Do You Need WSL?

Claude Code is a command-line tool that runs in the terminal, with native support for macOS and Linux. Windows users need WSL (Windows Subsystem for Linux) to use it.

WSL is an official Microsoft feature that lets you run a Linux environment directly on Windows — no virtual machine or dual-boot required. The setup process is straightforward and takes just a few steps.

Prerequisites

Before getting started, make sure you have the following:

  • Windows 10 (version 2004 or later) or Windows 11
  • Claude Max or Pro subscription: Claude Code requires an active Claude subscription. If you don't have one yet, check out our Apple ID registration guide to subscribe via the App Store
  • Stable internet connection: Since Hong Kong and Macau do not have direct access to Claude services, we recommend setting up OpenHK proxy service first to ensure a reliable connection
  • Sign in to Claude first: After connecting to OpenHK, open claude.ai in your browser and sign in to your account

Step 1: Install WSL

1. Open PowerShell as Administrator

Right-click the Windows Start button and select "Terminal (Admin)" or "Windows PowerShell (Admin)".

2. Run the Install Command

Paste the following command in PowerShell and press Enter:

wsl --install

This command automatically installs WSL 2 and the Ubuntu distribution. The installation may take a few minutes.

3. Restart Your Computer

After installation completes, restart your computer as prompted.

4. Set Up Your Ubuntu User

After restarting, Ubuntu will open automatically. On first launch, you'll be asked to:

  • Set a username (lowercase letters only, e.g., john)
  • Set a password (characters won't appear as you type — this is normal)

Remember this password — you'll need it when running sudo commands later.

Step 2: Update the System

In the Ubuntu terminal, update your system packages first:

sudo apt update && sudo apt upgrade -y

Enter the password you just set and wait for the update to complete.

Step 3: Connect to the Network (Essential for Hong Kong / Macau Users)

Since Hong Kong and Macau do not have direct access to Claude services, you'll need to use OpenHK proxy service. OpenHK uses TUN mode — no extra configuration needed, one click solves the network problem.

After connecting to OpenHK, test the connection from WSL:

curl -I https://claude.ai

If you see HTTP/2 200 or a similar response, the connection is working.

Step 4: Install Claude Code

In the Ubuntu terminal, run the install command:

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

After installation, verify it was successful:

claude --version

If you see a version number, the installation was successful.

Step 5: Log In to Claude Code

In your terminal, type:

claude

On first launch, Claude Code will display an authorization URL. Since WSL may not be able to open a browser automatically, you'll need to:

  1. Copy the URL shown in the terminal
  2. Open that URL in your Windows browser
  3. Complete the authorization in the browser

Once authorized, return to the WSL terminal and Claude Code will be ready to use.

Getting Started

Navigate to Your Working Directory

WSL can access your Windows files. The Windows C: drive is mounted at /mnt/c/. For example:

# Go to Windows Desktop
cd /mnt/c/Users/YourUsername/Desktop

# Go to Windows Documents folder
cd /mnt/c/Users/YourUsername/Documents

# Go to Linux home directory
cd ~

Launch Claude Code

Once you're in the target folder, type:

claude

Claude Code will automatically understand the file structure in the current folder. From here, usage is identical to macOS/Linux — just ask questions or give instructions in natural language.

For more usage tips and features, check out our Claude Code Beginner's Guide.

WSL Tips

  • Use Windows Terminal: Microsoft's official Windows Terminal is far better than the legacy Command Prompt — it supports tabs, custom themes, and multiple shell profiles. Free to download from the Microsoft Store
  • VS Code Integration: Install the "WSL" extension in VS Code to edit files inside WSL directly from VS Code — works great alongside Claude Code
  • File storage advice: For development projects, store your code in the Linux home directory (~/projects/) rather than under Windows directories for significantly faster read/write performance
  • Keep updated: Regularly run sudo apt update && sudo apt upgrade -y to keep your WSL environment up to date

FAQ

Q: Getting an error when running wsl --install? Make sure your Windows version meets the requirements (Windows 10 2004+). You may also need to enable virtualization technology (VT-x / AMD-V) in your BIOS. Most modern computers have this enabled by default, but older machines may need manual configuration.

Q: Can't open browser from WSL? This is expected. Copy the URL that Claude Code displays and paste it manually into your Windows browser to complete authorization.

Q: How do I copy and paste between WSL and Windows? In Windows Terminal, use Ctrl+C to copy and Ctrl+V to paste. In the legacy Command Prompt, right-click to paste.

Q: Want to learn more about Claude Code features? Check out our Claude Code Beginner's Guide, which covers model switching, Plan Mode, CLAUDE.md, and more advanced features.