Claude Code, Anthropic’s new AI-powered command line tool, offers developers a seamless way to delegate coding tasks directly from their terminal. However, Windows users attempting to install it through Windows Subsystem for Linux (WSL) may encounter several challenging errors. This guide walks through the common installation issues and provides step-by-step solutions to successfully run Claude Code on WSL.

Understanding the Installation Issues

When attempting to install Claude Code on Windows using WSL, you might encounter errors like:

Error: Claude Code is not supported on Windows.
Claude Code requires macOS or Linux to run properly.

Despite running the installation command in a WSL terminal, these errors occur because the system might still be detecting Windows environment variables or using Windows Node.js. The issue stems from WSL’s integration with Windows and how npm handles global package installations.

Verifying Your Environment

Before attempting any fixes, verify that you’re truly operating in a Linux environment:

uname -a

This should show information about your Linux kernel in WSL. If you see references to Microsoft or WSL2, you’re in the right environment.

Next, check for Windows references in your environment variables:

env | grep -i win

If you see many Windows paths, particularly in your PATH variable, this could be causing the detection issue.

Solution 1: Install Node.js for WSL (Not Windows)

The first critical step is ensuring you’re using the Linux version of Node.js, not the Windows one:

  1. Install Node.js specifically for your WSL distribution:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
  1. Verify you’re using the WSL version:
which node
which npm

Both commands should return paths starting with /usr/bin/ (Linux paths) rather than /mnt/c/ (Windows paths).

Solution 2: Set Up a User-Level npm Global Directory

To avoid permission issues with global installations, configure npm to use a directory in your home folder:

  1. Create a directory for global packages:
mkdir -p ~/.npm-global
  1. Configure npm to use this directory:
npm config set prefix '~/.npm-global'
  1. Add this directory to your PATH:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
  1. Now install Claude Code:
npm install -g @anthropic-ai/claude-code

This approach is preferred over using sudo for npm installations, as it’s more secure and follows best practices.

Solution 3: Force Node Environment

If you’re still encountering the Windows detection error, try forcing the environment variable:

FORCE_NODE_ENV=linux npm install -g @anthropic-ai/claude-code

Troubleshooting Permission Errors

If you see “EACCES: permission denied” errors when installing, this indicates a permissions issue when npm tries to write to system directories:

Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@anthropic-ai'

This reinforces the need for Solution 2 (user-level npm global directory) described above. While you could use sudo npm install -g @anthropic-ai/claude-code, it’s generally not recommended for security reasons.

Common Pitfalls to Avoid

  1. Don’t install from Windows paths: Make sure you’re not in a directory mounted from Windows (like /mnt/c/) when running the installation.

  2. Check for path conflicts: If you’ve installed Node.js both in Windows and WSL, make sure your WSL terminal is using the Linux version.

  3. Avoid sudo when possible: While sudo npm install works, it’s better to set up a user-level npm configuration.

  4. Clean failed installations: If you’ve had failed installations, clean up before trying again:

# If installation attempted to install in Windows directories
sudo rm -rf /mnt/c/Users/[YourUsername]/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code

# If installation attempted to install in Linux directories
sudo rm -rf /usr/lib/node_modules/@anthropic-ai/claude-code

Installing Claude Code on WSL is possible, but requires ensuring your environment is correctly configured. By following the solutions outlined in this guide, you can overcome the common installation errors and start using this powerful AI coding tool in your development workflow. Remember that proper Node.js and npm configuration is key to successfully installing not just Claude Code, but any npm packages within WSL.

If you continue experiencing issues, check the official Claude Code documentation or contact Anthropic support for further assistance. Happy coding with Claude!