If you are running Windows but prefer a real Linux development environment, WSL2 (Windows Subsystem for Linux) is the best way to run Claude Code CLI.
Claude Code is designed for Unix-like environments. While PowerShell works, WSL2 provides:
- Better shell compatibility
- Proper Unix tooling support
- Cleaner environment variable handling
- Better integration with Docker and DevOps workflows
If you are a cloud engineer, DevOps engineer, or backend developer, WSL2 is the recommended setup.
Why Use WSL2 for Claude CLI?
Claude Code was built primarily for Unix-based systems. Many developer tools behave more consistently in Linux.
Using WSL2 gives you:
- Full Bash support
- Native Linux file system
- Better scripting experience
- Proper PATH management
- Improved compatibility with Terraform, Docker, and CI/CD tools
If your daily workflow involves infrastructure, WSL2 is the better long-term solution.
System Requirements
Before starting, make sure you have:
- Windows 10 or Windows 11
- WSL2 enabled
- Ubuntu installed
Step 1 — Install WSL2 (If Not Installed)
Open PowerShell as Administrator and run:
wsl --install
Restart your computer when prompted.
After reboot:
- Launch Ubuntu from Start menu
- Create your Linux username
- Set your password
Verify WSL version:
wsl -l -v
You should see version 2.
Step 2 — Install Node.js Using NVM (Recommended)
Using NVM (Node Version Manager) is best practice.
Inside Ubuntu terminal:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
Reload shell:
source ~/.bashrc
Install Node.js LTS:
nvm install 20
nvm use 20
Verify installation:
node --version
npm --version
You should see version numbers.
Step 3 — Install Claude Code CLI
Install globally:
npm install -g @anthropic-ai/claude-code
Verify:
claude --version
If version appears, installation is successful.
Step 4 — Authenticate Claude CLI
Run:
claude
A browser window will open for login.
Choose your login method:
- Claude subscription account
- Anthropic Console account (API usage)
- 3rd-party platform (Bedrock, Vertex AI, etc.)
Alternative: Use API Key Authentication
If you prefer environment-based authentication:
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
Then run:
claude
Persist API Key Permanently
To avoid setting it every session:
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc
Now it loads automatically.
Common Troubleshooting
1. Command Not Found
If claude is not found:
which claude
If empty, check npm global path:
npm config get prefix
Make sure $HOME/.npm-global/bin or npm global bin directory is in your PATH.
Add to PATH if needed:
export PATH=$PATH:$(npm config get prefix)/bin
2. Permission Errors (EACCES)
Avoid using sudo with npm global installs.
If permission issue occurs, fix npm directory ownership:
sudo chown -R $(whoami) ~/.npm
Then reinstall.
3. WSL File System Tip
For better performance:
Store projects inside:
/home/your-username/
Avoid working inside:
/mnt/c/
Linux file system is faster inside WSL native directory.
PowerShell vs WSL2 Comparison
| Feature | PowerShell | WSL2 Ubuntu |
|---|---|---|
| Quick Setup | Yes | Requires install |
| Unix Compatibility | Limited | Full |
| DevOps Workflows | Moderate | Excellent |
| Docker Integration | Limited | Native |
| Recommended for Infra Engineers | Not ideal | Highly recommended |
If you work with:
- AWS
- Terraform
- Kubernetes
- CI/CD pipelines
WSL2 is strongly recommended.
Example Usage in WSL2
Debug logs:
cat ecs.log | claude -p "why is my ECS task restarting?"
Review Terraform:
claude "review my terraform IAM policy for least privilege"
Generate Bash script:
claude -p "create a bash script to rotate logs older than 30 days"
Updating Claude CLI in WSL2
To update:
npm update -g @anthropic-ai/claude-code
Verify:
claude --version
Security Best Practices
- Never commit API keys
- Use environment variables
- Avoid exposing production secrets
- Review generated IAM policies carefully
- Validate infrastructure before applying
AI should assist your workflow, not replace engineering validation.
Final Thoughts
Running Claude Code CLI inside WSL2 Ubuntu gives you the most stable and powerful Linux-based developer experience on Windows.
For DevOps engineers, cloud engineers, and automation specialists, this setup integrates AI directly into your terminal workflow without sacrificing Unix compatibility.
If your goal is professional cloud engineering workflow, WSL2 is the correct long-term setup.