Fix Claude Code CLI Installation Errors: Complete Troubleshooting Guide

If you're having trouble installing Claude Code CLI, you're not alone. This guide covers the most common installation issues and their solutions for macOS, Windows, and Linux.

Quick Fix: The Recommended Installation Method

Before troubleshooting, ensure you're using the official installer:

macOS and Linux:

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

Windows (via WSL - Recommended):

# In WSL terminal
curl -fsSL https://claude.ai/install.sh | sh

Windows (Native PowerShell - Experimental):

irm https://claude.ai/install.ps1 | iex

After installation, restart your terminal and run:

claude --version

"command not found: claude"

This is the most common issue after installation.

Cause 1: PATH Not Updated

The installer adds Claude to your PATH, but your current terminal session doesn't see it yet.

Quick Fix:

# For zsh (macOS default)
source ~/.zshrc

# For bash
source ~/.bashrc

# Or simply open a new terminal window

Cause 2: PATH Configuration Missing

Check if the PATH was added to your shell config:

# Check your PATH
echo $PATH | tr ':' '\n' | grep -E "(local|claude)"

# You should see one of these:
# /usr/local/bin
# ~/.local/bin
# /home/username/.local/bin

If missing, add it manually:

# For zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Cause 3: Wrong Shell Config File

If you switched shells (e.g., from bash to zsh), the PATH may be in the wrong file:

# Check your current shell
echo $SHELL

# If it shows /bin/zsh but Claude was installed for bash,
# copy the PATH configuration:
cat ~/.bashrc | grep -i path >> ~/.zshrc
source ~/.zshrc

Permission Denied Errors

During Installation

Error: Permission denied: /usr/local/bin/claude

Fix: The installer should install to ~/.local/bin (user directory), not /usr/local/bin (system directory). If you see this:

1. Don't use sudo - it creates permission problems later
2. Re-run the installer without sudo:

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

When Running Claude

Error: Permission denied: ~/.local/bin/claude

Fix:

# Make the binary executable
chmod +x ~/.local/bin/claude

# Verify
ls -la ~/.local/bin/claude
# Should show: -rwxr-xr-x

npm Installation Issues

If you installed via npm (not recommended but still works):

"npm: command not found"

Install Node.js first:

macOS:

brew install node

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

npm Permission Errors

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Fix: Configure npm to use a user directory:

# Create npm global directory
mkdir ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

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

# Now install Claude
npm install -g @anthropic-ai/claude-code

Migrating from npm to Official Installer

If you previously installed via npm and want to switch:

# Remove npm version
npm uninstall -g @anthropic-ai/claude-code

# Install official version
curl -fsSL https://claude.ai/install.sh | sh

# Verify
claude --version

Your configuration in ~/.claude/ is preserved during migration.

macOS-Specific Issues

Xcode Command Line Tools Required

Error: xcode-select: error: command line tools are not installed

Fix:

xcode-select --install

Wait for the installation to complete, then retry the Claude installation.

Apple Silicon (M1/M2/M3) Issues

Claude Code runs natively on Apple Silicon. If you encounter issues:

1. Ensure you're not running under Rosetta:

uname -m
# Should show: arm64 (not x86_64)

2. If using Homebrew, ensure it's the ARM version:

which brew
# Should show: /opt/homebrew/bin/brew (not /usr/local/bin/brew)

Gatekeeper Blocking Installation

Error: "claude" cannot be opened because it is from an unidentified developer

Fix:

# Remove quarantine attribute
xattr -d com.apple.quarantine ~/.local/bin/claude

Windows-Specific Issues

Best Practice: Use WSL

Windows Subsystem for Linux provides the most reliable experience:

1. Install WSL:

wsl --install

2. Restart your computer

3. Open Ubuntu (or your chosen distro) and install Claude:

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

PowerShell Execution Policy

Error: running scripts is disabled on this system

Fix:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Antivirus Interference

Windows Defender or other antivirus software may block the installation:

1. Temporarily disable real-time protection
2. Run the installer
3. Re-enable protection
4. Add Claude's directory to exclusions if issues persist

Native Windows Path Issues

If using native Windows (not WSL), PATH may not update:

1. Search for "Environment Variables" in Windows
2. Edit "Path" under User variables
3. Add: %USERPROFILE%\.local\bin
4. Restart PowerShell

Linux-Specific Issues

Missing Dependencies

Error: error while loading shared libraries

Fix (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install -y libssl-dev ca-certificates

Fix (Fedora/RHEL):

sudo dnf install -y openssl-devel ca-certificates

curl Not Installed

Error: curl: command not found

Fix:

# Ubuntu/Debian
sudo apt-get install -y curl

# Fedora/RHEL
sudo dnf install -y curl

# Then run the installer
curl -fsSL https://claude.ai/install.sh | sh

Verifying Your Installation

After installation, verify everything works:

# Check version
claude --version

# Check installation path
which claude

# Run diagnostics
claude doctor

# Test authentication
claude auth status

Expected Output

Claude Code CLI v1.x.x
/home/username/.local/bin/claude
All checks passed!
Not authenticated (run 'claude' to log in)

Authentication After Installation

Once installed, authenticate with your Anthropic account:

claude

This opens a browser for authentication. After logging in, you'll see:

Successfully authenticated as: [email protected]

Authentication Troubleshooting

Can't open browser automatically:

# Copy the URL shown and open it manually in a browser
# Or use device code flow:
claude auth login --device

Authentication fails:

1. Ensure you have a Claude.ai account with Claude Code access
2. Check your subscription includes Claude Code (Pro plan or higher)
3. Try logging out of claude.ai in your browser first

Uninstalling and Reinstalling

If all else fails, try a clean reinstall:

# Remove Claude CLI
rm -rf ~/.local/bin/claude
rm -rf ~/.claude

# Clear npm cache (if used npm)
npm cache clean --force

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

Getting Help

If you're still having issues:

1. Check the official docs: Claude Code Documentation
2. Search GitHub issues: Claude Code Issues
3. Run diagnostics: claude doctor provides detailed system information

Next Steps

• Where Configuration Files Are Stored
• How to Fix Freezing Issues
• How to Fix Permission Errors
• How to Use Plan Mode