What a title. Anyways, figured I'd make a quick little guide on how to do this.

Prerequisites:

• VS Code

• Git repository (not an actual requirement, just how I did it with my limited bash knowledge)

Steps

1. Open up PowerShell and install WSL with:

cmd
wsl --install

2. Set Ubuntu as default (important!):

cmd
wsl --set-default Ubuntu

3. Open a WSL terminal

Tip: check the upper left dropdown menu in Windows Terminal that will show various terminals available

4. Install Claude Code in the WSL terminal (if you have issues, please refer to Anthropic's guide):

bash
npx u/anthropic-ai/claude-code

5. Make a directory for your projects:

bash
mkdir coolProjects && cd coolProjects

6. Clone your project (optional):

bash
git clone https://github.com/yourrepo.git

7. Open VS Code

8. Install the official WSL extension

9. Press F1

10. Type "WSL"

IMPORTANT

11. Select "WSL: Connect to WSL using Distro"

Choose Ubuntu.

From here you can now open a folder within VS Code.

How do you know it worked? Check the bottom left corner of VS Code - it should say "WSL: Ubuntu" and your Claude Code extension should be enabled!

Troubleshooting

If you get Alpine Linux errors or "libstdc++ required" messages: This usually happens if you have Docker Desktop installed and it became your default WSL distribution instead of Ubuntu. Run wsl --list --verbose to check, and if docker-desktop-data has an asterisk (*), run wsl --set-default Ubuntu to fix it. That's why step 2 is so important!

Hope this is helpful!

Complete and Corrected Guide: WSL + Claude Code + Cursor Setup for Windows

Overview

This guide walks you through setting up a professional development environment with WSL2, Cursor, and command-line tools like Claude Code – based on proven best practices.

Phase 1: Windows Preparation

1. Windows Updates

• Settings → Update & Security → Windows Update

• Install all available updates and restart PC if needed

2. Install Important Dependencies

Open PowerShell as Administrator and ensure important developer tools are installed:

• Visual C++ Redistributables (all common versions)

• DirectX (current version)

These are often necessary for compiling tools (e.g., via npm or pyenv).

3. Enable WSL Features

Open PowerShell as Administrator:

powershell
# Enable WSL and Virtual Machine Platform
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart Windows: shutdown /r /t 0

Phase 2: WSL2 Installation

4. Install WSL2 (after restart)

PowerShell as Administrator:

powershell
# Install WSL2 with default distribution (Ubuntu)
wsl --install

If this doesn't work, specify explicitly: wsl --install -d Ubuntu-22.04

Restart Windows again.

5. Verify WSL2 Installation

After restart, open PowerShell:

powershell
wsl -l -v

Expected output should show VERSION as 2.

If 1 is displayed, upgrade to WSL2:

powershell
# Set WSL2 as default
wsl --set-default-version 2
# Convert existing distribution to version 2
wsl --set-version Ubuntu-22.04 2

6. Complete Ubuntu Setup

• An Ubuntu terminal window opens automatically

• Create a username (lowercase, no spaces)

• Create a password

• Wait for installation to complete

7. Update Ubuntu

In Ubuntu terminal:

bash
sudo apt update && sudo apt upgrade -y

Phase 3: Install Developer Tools in WSL

8. Install Essential Tools

In Ubuntu terminal:

bash
# Git, Curl and Build Tools
sudo apt install git curl build-essential -y

# Python dependencies
sudo apt install python3-pip python3-venv -y

9. Configure Git

bashgit config --global user.name "Your Name"
git config --global user.email "[email protected]"
git config --global init.defaultBranch main

10. Install Python with pyenv (in WSL)

Install pyenv dependencies:

bashsudo apt install make libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev -y

Install pyenv:

bash
curl https://pyenv.run | bash

Add pyenv to shell and reload:

bashecho 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

Install a Python version and set as default:

bashpyenv install 3.11.8
pyenv global 3.11.8

11. Install Node.js with nvm (in WSL)

[NOTE] We use the officially recommended command to always get the latest nvm installation script.

bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

Reload shell so nvm is available:

bash
source ~/.bashrc

Install latest LTS version of Node.js and use it:

bashnvm install --lts
nvm use --lts

Phase 4: Cursor Installation and Configuration

12. Install Cursor on Windows

Download Cursor from the official website and install it.

13. Install Important Cursor Extensions

In Cursor via Ctrl + Shift + X:

• Remote - WSL (ms-vscode-remote.remote-wsl)

• Remote Development (ms-vscode-remote.vscode-remote-extensionpack)

• Python (ms-python.python)

• Prettier (esbenp.prettier-vscode)

14. Configure Cursor WSL Settings

Ctrl + , → Settings, search and set:

json{
    "terminal.integrated.defaultProfile.windows": "WSL",
    "terminal.integrated.cwd": "~/dev/projects"
}

[NOTE] The setting remote.WSL.fileWatcher.polling is usually no longer needed and can cause high CPU usage. Only add it if you notice that file changes aren't being detected.

Phase 5: Set Up Project Structure

15. Create Project Structure in WSL

bash
# Main development folder
mkdir -p ~/dev/projects

[NOTE] You can create additional subfolders as needed.

16. Set Up Default Terminal Path and Aliases

bash
# Edit .bashrc
nano ~/.bashrc

Add the following at the end of the file:

bash
# Change to project folder when opening a new terminal
cd ~/dev/projects

# Useful aliases
alias dev='cd ~/dev/projects'
alias home='cd ~'

Save: Ctrl + O, Enter, Ctrl + X. Reload: source ~/.bashrc

Phase 6: Claude Code Installation

17. Install Claude Code

bash
# Switch to any folder, e.g., the project folder
cd ~/dev/projects

# Install Claude Code globally (DO NOT use sudo)
npm install -g @anthropic-ai/claude-code

18. Claude Code Setup and Authentication

After installation, set up Claude Code with these specific steps:

A. Navigate to your project directory

bash
cd ~/dev/projects

B. Start Claude Code

bash
claude

C. Complete Authentication

When you first run claude, you'll see authentication options:

1. Anthropic Console (Pay-as-you-go):

   • Choose this option if you want to pay per API usage

   • Requires active billing at console.anthropic.com

   • Claude will open a browser window for OAuth authentication

   • If you're in WSL without GUI, the URL will be printed in terminal

   • Open the URL on any computer and sign in with your Anthropic credentials

2. Claude App (Pro/Max Plan):

   • Choose this if you have a Claude Pro ($20/month) or Max ($100-200/month) subscription

   • Log in with your Claude.ai account credentials

   • This provides a unified subscription for both Claude Code and web interface

D. IDE Integration (Automatic)

For VS Code/Cursor integration:

1. Automatic Extension Installation:

   • When you run claude from within VS Code/Cursor's integrated terminal, the IDE extension is installed automatically

   • No manual installation steps required

2. Access Claude Code in VS Code/Cursor:

   • Open VS Code/Cursor in your project folder

   • Run claude in the integrated terminal (Ctrl + Shift + `)

   • Look for the Claude icon that appears in the activity bar, or

   • Press Ctrl+ESC (Windows/Linux) or Cmd+ESC (Mac)

   • This opens Claude Code in a WebView panel within your IDE

E. Test the Installation

bash
# Check if Claude Code is working
claude --version

# Start an interactive session
claude

# In the Claude Code interface, try:
/help

F. Initial Project Setup (Recommended)

bash
# Generate a project guide (helps Claude understand your codebase)
# In Claude Code session, ask:
"Please create a CLAUDE.md file that documents this project structure and setup"

# Commit the generated file
git add CLAUDE.md
git commit -m "Add Claude Code project documentation"

Phase 7: Test Cursor-WSL Integration

19. Connect Cursor to WSL

• Open Cursor

• Click the green >< icon in the bottom left and select "Connect to WSL"

20. Open Workspace in WSL

In WSL terminal:

bash
# Navigate to your project folder
dev 
# Use alias

# Open Cursor in current directory
code .

Verification: Cursor opens and shows "WSL: Ubuntu-22.04" in the bottom left. The integrated terminal (Ctrl + Shift + ) shows a Linux prompt ($`).

Phase 8: Test the Entire Environment

21. Check Versions

In Cursor WSL terminal:

bashgit --version
python --version  
# Should show the pyenv version
node --version    
# Should show the nvm version
npm --version

22. Check Paths

bashwhich python  
# Should point to pyenv shim path
which node    
# Should point to nvm path
pwd           
# Should be /home/username/dev/projects

23. Test with Python Virtual Environment

bashmkdir test-python && cd test-python
python -m venv venv
source venv/bin/activate
pip list
deactivate
cd .. && rm -rf test-python

Troubleshooting (Updated)

command not found: claude-code

• Ensure you used the correct package name with npm install -g <package-name>

• Check if nvm is loaded correctly (nvm current should show a version)

EACCES errors with npm install -g

[CORRECTION] This error should not occur with this guide. If it does, nvm is not active correctly. Ensure the nvm lines are in your .bashrc and you've run source ~/.bashrc. Never run npm with sudo when using nvm.

Issues with Cursor-WSL Integration

• Restart WSL: wsl --shutdown in PowerShell, then reopen Ubuntu

• Reset remote caches in Cursor: Ctrl + Shift + P → "Remote-WSL: Kill WSL Server"

Completion Checklist

✅ WSL2 enabled and Ubuntu installed & updated
✅ Git configured
✅ Python installed with pyenv
✅ Node.js installed with nvm (correct method, no manual npm prefix)
✅ Cursor installed with WSL extensions
✅ Project structure created
✅ "Claude Code" (or other tool) correctly installed
✅ Cursor-WSL integration working
✅ All tests successful

🎉 Installation Complete!

[IMPORTANT] Never use sudo with npm when nvm is installed, as this can cause permission issues and security risks.

[CORRECTION] This section replaces the erroneous "Configure NPM without sudo" phase. nvm already handles this correctly.