Complete Guide: Setting Up Claude Code with WSL and Cursor on Windows 2025

If you're here, you probably want to harness AI for coding but found the setup process confusing or frustrating. Maybe you've tried other guides only to hit mysterious errors or incomplete instructions. This guide is different.

I'm going to walk you through building a professional development environment that combines Windows stability with Linux power, integrated with an AI assistant that can write, debug, and explain code. By the end, you'll have the same setup used by developers at top tech companies.

What You'll Build

Think of this as constructing a smart house for developers. We'll lay the foundation (Windows + WSL2), build the frame (development tools), install utilities (Python + Node.js), add the interface (Cursor IDE), and finally connect the AI brain (Claude Code).

Your completed environment will include:

Linux subsystem inside Windows - Access both ecosystems without dual-booting
Modern AI-powered code editor - Like having an experienced programmer beside you
Version control integration - Track every change to your code
Python and JavaScript environments - The two most popular programming languages
AI coding assistant - Natural language commands for complex tasks

⏱️ Time Investment

Plan for 2-3 hours of setup time. Most of this is waiting for downloads. You'll need Windows 10 (version 2004+) or Windows 11, administrator access, and 10GB free disk space.

Phase 1: Preparing Windows Foundation

Before building anything, we need to ensure Windows has all necessary components. Incomplete updates are the #1 cause of WSL installation failures.

Step 1: Complete Windows Updates

Press Windows key → type "Settings" → "Update & Security" → "Windows Update" → "Check for updates"

Install everything available, even if it requires multiple restarts. This prevents compatibility issues later.

Step 2: Install System Components

Right-click Start → "Windows PowerShell (Admin)" or "Terminal (Admin)" on Windows 11

# Install Visual C++ Redistributables
Invoke-WebRequest -Uri "https://aka.ms/vs/17/release/vc_redist.x64.exe" -OutFile "$env:TEMP\vc_redist.x64.exe"
Start-Process -FilePath "$env:TEMP\vc_redist.x64.exe" -ArgumentList "/install", "/quiet", "/norestart" -Wait

# Install Windows Terminal (if needed)
winget install Microsoft.WindowsTerminal

Step 3: Enable WSL2 Features

In your 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 10

Phase 2: Installing WSL2 and Ubuntu

After restart, we'll install Ubuntu as a subsystem within Windows. This gives you a complete Linux environment while maintaining access to Windows files and applications.

Step 4: Install Ubuntu via WSL2

Open PowerShell as Administrator again:

# Download WSL2 kernel update
Invoke-WebRequest -Uri "https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi" -OutFile "$env:TEMP\wsl_update_x64.msi"
Start-Process -FilePath "$env:TEMP\wsl_update_x64.msi" -ArgumentList "/quiet" -Wait

# Set WSL2 as default
wsl --set-default-version 2

# Install Ubuntu 22.04 LTS
wsl --install -d Ubuntu-22.04

Step 5: Configure Ubuntu

Ubuntu will open automatically. Create your Linux user account when prompted:

Choose lowercase username with no spaces (e.g., "johnsmith")
Create a strong password (you won't see characters as you type)
Remember this password for sudo commands

Step 6: Update Ubuntu

In your Ubuntu terminal:

# Update package lists
sudo apt update

# Upgrade all packages
sudo apt upgrade -y

🎯 Getting Lost?

Join our Discord for real-time help with setup issues and connect with other developers

Get Help

Phase 3: Development Environment

Now we'll install the core tools for modern software development. Think of this as stocking your workshop with professional-grade equipment.

Step 7: Essential Development Tools

# Core development tools
sudo apt install git curl build-essential python3-pip python3-venv -y

# Python development dependencies
sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev -y

Step 8: Configure Git

# Set your Git identity (replace with your info)
git config --global user.name "Your Full Name"
git config --global user.email "[email protected]"

# Set sensible defaults
git config --global init.defaultBranch main
git config --global color.ui auto
git config --global pull.rebase false

Step 9: Install Python with pyenv

Different projects need different Python versions. pyenv lets you manage multiple versions easily:

# Install pyenv
curl https://pyenv.run | bash

# Add to shell configuration
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# Reload shell
source ~/.bashrc

# Install Python 3.11.8
pyenv install 3.11.8
pyenv global 3.11.8

# Verify installation
python --version

Step 10: Install Node.js with nvm

Similar to pyenv, nvm manages multiple Node.js versions:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload shell
source ~/.bashrc

# Install latest LTS Node.js
nvm install --lts
nvm use --lts

# Verify installation
node --version
npm --version

Phase 4: Setting Up Cursor IDE

Cursor is a modern code editor built specifically for AI-assisted development. Unlike traditional editors, it understands context across your entire project.

We install Cursor on Windows, not WSL2. This gives you the full graphical interface while accessing your Linux development environment.

Step 11: Install Cursor

1. Open your browser and go to https://cursor.sh

2. Download the Windows installer

3. Run the installer with default options

4. Launch Cursor from Start menu

Step 12: Install Essential Extensions

Press Ctrl + Shift + X to open Extensions and install:

Remote — WSL by Microsoft (enables WSL2 integration)
Python by Microsoft (Python language support)
Prettier — Code formatter (automatic code formatting)
GitLens — Git supercharged (enhanced Git integration)

Step 13: Configure WSL Integration

Press Ctrl + , to open settings, then click "Open Settings (JSON)" and add:

{
  "terminal.integrated.defaultProfile.windows": "WSL",
  "terminal.integrated.cwd": "~/dev/projects",
  "remote.WSL.fileWatcher.polling": true,
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/venv/**": true,
    "**/__pycache__/**": true
  }
}

Phase 5: Organizing Your Workspace

A well-organized project structure makes development more efficient and helps you find files quickly as projects grow.

Step 14: Create Directory Structure

In your Ubuntu terminal:

# Create main development directories
mkdir -p ~/dev/{projects,tools,workspace,templates}

# Create project-specific subdirectories
mkdir -p ~/dev/projects/{python-projects,js-projects,ai-automation,web-projects,learning}

# Verify structure
tree ~/dev/ || ls -la ~/dev/

Step 15: Add Productive Aliases

Open shell configuration:

nano ~/.bashrc

Add these shortcuts to the bottom:

# Navigation shortcuts
alias dev='cd ~/dev/projects'
alias tools='cd ~/dev/tools'
alias py='cd ~/dev/projects/python-projects'
alias js='cd ~/dev/projects/js-projects'
alias web='cd ~/dev/projects/web-projects'
alias learn='cd ~/dev/projects/learning'

# Git shortcuts
alias gs='git status'
alias ga='git add'
alias gc='git commit'
alias gp='git push'
alias gl='git log --oneline'

# Python shortcuts
alias py3='python3'
alias venv='python3 -m venv'
alias activate='source venv/bin/activate'

# Utilities
alias ll='ls -alF'
alias ..='cd ..'
alias ...='cd ../..'

Save with Ctrl + O, Enter, then exit with Ctrl + X

# Activate aliases
source ~/.bashrc

# Test it works
dev
pwd

Phase 6: Configuring NPM

NPM often causes permission problems. We'll configure it to avoid these issues entirely.

Step 16: Set Up NPM Global Directory

# Create directory for global NPM packages
mkdir ~/.npm-global

# Configure NPM to use this directory
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Verify configuration
npm config get prefix

Phase 7: Installing Claude Code

Finally, we'll install Claude Code - Anthropic's AI-powered command-line assistant that integrates with your development environment.

Step 17: Install Claude Code

# Navigate to projects directory
dev

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Step 18: Authenticate Claude Code

Start Claude Code for initial setup:

claude

Follow the authentication prompts. You can use either:

Claude Pro/Max subscription - Log in with Claude.ai credentials
Anthropic Console - Pay-as-you-go billing with OAuth

Phase 8: Integration Testing

Now we'll connect everything together and verify that Claude Code works seamlessly within your setup.

Step 19: Connect Cursor to WSL2

1. Open Cursor on Windows

2. Click the green icon in bottom-left corner

3. Select "Connect to WSL"

4. Choose "Ubuntu-22.04"

5. Wait for server components to install

6. Verify "WSL: Ubuntu-22.04" appears in bottom-left

Step 20: Open Development Workspace

With Cursor connected to WSL2:

1. Press Ctrl + O to open folder

2. Navigate to /home/yourusername/dev/projects

3. Click "Open"

Alternatively, use terminal method:

# In Cursor's integrated terminal (Ctrl + Shift + `)
dev
code .

Step 21: Test Claude Code Integration

In Cursor's integrated terminal:

claude

Test the integration:

/status

This shows authentication status and confirms Claude Code detected Cursor as your IDE.

🚀 Everything Working?

Join our developer community to share your setup and get tips from other Claude Code users

Join Community

Phase 9: Comprehensive Testing

Let's verify every component works correctly with thorough testing.

Step 22: System Verification

# Check all component versions
echo "=== System Versions ==="
lsb_release -a | grep Description
echo "Git: $(git --version)"
echo "Python: $(python --version)"
echo "Node.js: $(node --version)"
echo "NPM: $(npm --version)"
echo "pyenv: $(pyenv --version)"
echo "nvm: $(nvm --version)"

echo -e "\n=== Path Verification ==="
echo "Python location: $(which python)"
echo "Node location: $(which node)"
echo "Current directory: $(pwd)"

echo -e "\n=== NPM Configuration ==="
echo "NPM prefix: $(npm config get prefix)"
echo "NPM global bin in PATH: $(echo $PATH | grep -o '[^:]*npm-global[^:]*')"

Step 23: Test Python Environment

# Navigate to Python projects
py

# Create test project
mkdir test-python-env && cd test-python-env

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate

# Verify activation (should see "(venv)" in prompt)
which python
python --version

# Install test package
pip install requests

# List packages
pip list

# Clean up
deactivate
cd .. && rm -rf test-python-env

Step 24: Test Node.js Environment

# Navigate to JavaScript projects
js

# Create test project
mkdir test-node-env && cd test-node-env

# Initialize Node.js project
npm init -y

# Install popular package
npm install lodash

# Create test file
echo 'const _ = require("lodash"); console.log("Lodash version:", _.VERSION);' > test.js

# Run test
node test.js

# Clean up
cd .. && rm -rf test-node-env

Step 25: Test Claude Code

# Return to main projects
dev

# Create Claude test directory
mkdir claude-test && cd claude-test

# Start Claude Code
claude

In Claude Code, test these commands:

/help - Shows available commands
create a simple Python script that prints "Hello, Claude Code!"
/status - Shows authentication and model info

Exit with exit or Ctrl + C

Understanding Your Environment

Your setup creates a sophisticated development environment bridging Windows and Linux with AI assistance:

WSL2 provides full Linux kernel alongside Windows without virtual machine overhead
Cursor serves as your Windows-native interface working seamlessly with Linux tools
Version managers (pyenv/nvm) prevent dependency conflicts between projects
Claude Code integrates with the entire stack as your AI pair programming partner

Critical Platform Differences

Understanding these prevents common errors:

File paths: Windows uses C:\Users\username, Linux uses /home/username
Commands: Windows uses dir, Linux uses ls
Virtual environments: Windows uses venv\Scripts\activate, Linux uses source venv/bin/activate
Package managers: Windows has winget/chocolatey, Linux uses apt

🔧 Common Issues

Claude Code EACCES errors: Check NPM config with npm config get prefix
Windows paths in WSL2: You're in wrong location, run cd then dev
Cursor can't connect: Check WSL2 status with wsl --status
Permission errors: Never use sudo with npm install

Best Practices

Always use virtual environments for Python projects
Install Node packages locally unless they're global development tools
Commit code changes regularly with Git for version control
Keep CLAUDE.md files updated with project-specific instructions

Quick Reference Commands

Navigation: dev, py, js, web
Python project: py → mkdir project-name → cd project-name → python -m venv venv → source venv/bin/activate
Node.js project: js → mkdir project-name → cd project-name → npm init -y
Open Cursor: code . from any project directory
Start Claude Code: claude from project directory
Access Windows files: /mnt/c/ for C drive in WSL2
Access WSL2 files: \\wsl$\Ubuntu-22.04\home\username in Windows Explorer

Final Verification Checklist

Windows fully updated and restarted
WSL2 enabled and Ubuntu 22.04 installed
Ubuntu system packages updated
Git configured with your name and email
Python 3.11.8 installed via pyenv and set as default
Node.js LTS installed via nvm and set as default
NPM global directory configured properly
Cursor installed on Windows with WSL extension
Directory structure created in ~/dev/projects
Shell aliases configured and working
Claude Code installed and authenticated
Cursor connects successfully to WSL2
Integrated terminal opens in ~/dev/projects
Claude Code runs successfully in Cursor
Python virtual environment test passes
Node.js project test passes
All version checks return expected results

Next Steps

Once comfortable with basics, consider adding:

Docker for containerized development
Jupyter for data science projects
React/Vue for web development
PostgreSQL/MongoDB for database work
Cloud tools for AWS, Azure, or Google Cloud

Your development environment is now complete and ready for serious software development. The combination of Windows stability, Linux development tools, modern IDE features, and AI assistance provides a powerful foundation for any programming project.

Take time to practice with the tools and gradually incorporate advanced features as you become comfortable with the workflow. Welcome to the future of AI-assisted development!