Introduction: That Error Message Is More Common Than You Think
If you've hit a wall with claude code installation failed, you're not alone. Developers across the board from seasoned engineers to first-time AI tool users run into this exact wall. The frustrating part? The error message itself often tells you almost nothing useful. You get a vague failure notice, maybe a log that makes no sense, and a growing urge to give up
Don't. Every single installation error has a fix. This guide is built specifically to walk you through every known cause of Claude Code not installing, what each error actually means, and how to resolve it step by step, without the guesswork.
Whether you're running macOS, Windows, or Linux, whether it's a permissions issue or a Node.js version mismatch, this is the only guide you need to get Claude Code running today.
What "Claude Code Installation Failed" Actually Means
Claude Code is Anthropic's AI-powered command-line coding assistant. It installs as an npm global package (@anthropic-ai/claude-code) and requires a working Node.js environment, npm, and proper shell configuration to function.
When you see installation failed, it's not one specific error it's a catch-all symptom that can point to several different root causes:
Node.js version incompatibility
npm permission errors
PATH configuration issues
Stale lock files from interrupted installs
Corporate network/firewall blocking downloads
TLS/SSL certificate errors
Terminal incompatibility (especially on Windows)
Authentication failures post-install
The key is identifying which of these you're dealing with. The sections below map every symptom to its exact fix.
Why Claude Code Fails to Install The Real Causes
1. Wrong or Missing Node.js Version
Claude Code requires Node.js version 18 or later. If you're running an older version or if your system has multiple Node versions and the wrong one is active the installation will either fail silently or crash immediately after launch.
This is the single most common cause, and it trips up even experienced developers who haven't updated their Node environment in a while.
2. npm Permission Errors (EACCES)
Running npm install -g with sudo might seem like a quick fix when you hit a permission error, but it creates a worse problem: it makes your npm global directory root-owned. Future installs will keep failing until you manually fix the directory ownership.
3. Stale Lock File From a Previous Failed Install
This is a particularly nasty one. If a previous installation was interrupted — by a crash, a macOS Gatekeeper kill, or manual cancellation — a lock file gets left behind at ~/.local/state/claude/locks/. The next time you try to install, the installer sees the lock file, thinks another process is running, and refuses to proceed.
Infuriatingly, the error message says both "Installation failed" and "Installation complete" — which makes no sense and helps no one. But the fix is simple once you know about it.
4. PATH Not Updated
Even a successful installation can leave you staring at command not found: claude. Why? Because the installer added the binary to your PATH in your shell config file (.zshrc, .bashrc, etc.), but your current terminal session hasn't loaded that updated config yet.
On Windows, this is even more common — especially when npm installs to a user-level AppData directory that isn't in the system PATH.
5. Terminal Incompatibility on Windows
Windows Git Bash doesn't support TTY (raw terminal mode), which Claude Code's interactive CLI requires. Trying to run the installer or the tool itself in Git Bash gives you:
Error: Raw mode is not supported on the current process.stdin |
The fix is to use PowerShell instead. It's that simple but nobody tells you upfront.
6. Network/Proxy Blocks
The installer downloads from storage.googleapis.com. Corporate networks frequently block this domain. Behind a firewall or proxy, the download silently stalls or fails with a network timeout, and the error message gives you no indication that a blocked URL is the culprit.
7. TLS Certificate Errors
Companies that intercept HTTPS traffic (common in enterprise environments) inject their own SSL certificates. Node.js doesn't trust these by default, so you get SELF_SIGNED_CERT_IN_CHAIN errors during install or on first run.
Step-by-Step Fix Guide for Every Common Error
Fix 1: Check and Update Node.js First
Before anything else, verify your Node version:
bash node -v |
If you're not on Node 18 or later, update using nvm:
bash nvm install --lts nvm use --lts node -v # Should show v20.x or higher |
No nvm? Install it first:
bash # On macOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc # or ~/.bashrc |
Alternatively, use Anthropic's curl installer, which bundles its own Node.js runtime and sidesteps version conflicts entirely:
bash curl -fsSL https://claude.ai/install.sh | bash |
Fix 2: Resolve npm EACCES / Permission Errors
Never use sudo npm install -g. Instead, fix your npm global directory:
bash npm config set prefix ~/.npm-global |
Then add it to your PATH. Open ~/.zshrc or ~/.bashrc and add:
bash export PATH="$HOME/.npm-global/bin:$PATH" |
Reload your shell:
bash source ~/.zshrc |
Now retry the installation:
bash npm install -g @anthropic-ai/claude-code |
Fix 3: Remove a Stale Lock File (Mac/Linux)
If you see contradictory messages like "Installation failed" followed immediately by "Installation complete," a stale lock file is almost certainly the cause.
Find and remove it:
bash rm ~/.local/state/claude/locks/*.lock |
Then rerun:
bash curl -fsSL https://claude.ai/install.sh | bash |
This is one of those bugs that has bitten many users. The official GitHub issue tracker documents this exact problem the installer doesn't check whether the process that created the lock is still alive, so a crashed install leaves a permanent ghost that blocks every future attempt.
Fix 4: Fix PATH After Installation (claude: command not found)
If installation appeared to succeed but claude returns "command not found":
bash # Reload your shell config source ~/.zshrc # For zsh (macOS default) source ~/.bashrc # For bash (Linux default) |
Or simply open a new terminal window. If that still doesn't work, find where Claude was installed:
bash export PATH="/path/from/above:$PATH" |
Fix 5: Windows — Switch from Git Bash to PowerShell
On Windows, if you're getting TTY errors or raw mode errors, stop using Git Bash. Open Windows PowerShell (not Command Prompt, not Git Bash) and run:
bash # Step 1: Add Node.js to PATH (current session) $env:Path += ";C:\Program Files\nodejs" # Step 2: Verify Node is working node --version # Step 3: Install Claude Code npm install -g @anthropic-ai/claude-code # Step 4: Add npm global directory to PATH $env:Path += ";C:\Users\YourUsername\AppData\Roaming\npm" # Step 5: Verify claude --version |
To make these PATH changes permanent, add them through System Properties → Environment Variables in Windows, or use the PowerShell profile.
Fix 6: WSL — Fix Windows Node Leaking Into Linux PATH
If you're using WSL and Claude Code runs the Windows version of Node instead of the Linux version:
bash export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH" |
This ensures the Linux Node binary takes precedence over whatever Windows has in its PATH.
Fix 7: Fix Corporate Proxy / Network Blocks
If you're behind a proxy:
bash export HTTPS_PROXY=http://your-proxy-server:port export HTTP_PROXY=http://your-proxy-server:port |
Then run the installer. If storage.googleapis.com is fully blocked by your IT team, ask them to whitelist the domain or request the offline installation package directly from Anthropic support.
Fix 8: Fix TLS/SSL Certificate Errors
If you see SELF_SIGNED_CERT_IN_CHAIN or similar errors:
bash export NODE_EXTRA_CA_CERTS=/path/to/your-corporate-ca.pem |
Add this line to your ~/.zshrc or ~/.bashrc so it persists across sessions. Your IT team should be able to provide the CA certificate file.
Fix 9: Authentication Issues After Install
Installation worked, but claude won't authenticate? Try these in order:
1.Check if your API key is actually set:
bash echo $ANTHROPIC_API_KEY |
If it's empty, export it in the correct shell:
bash export ANTHROPIC_API_KEY="your-key-here" |
2.OAuth conflict: If you previously ran /login and now want to use an API key, the OAuth session takes precedence. Run /logout first, then set your key.
3.Remote/SSH environments: The browser-based login flow won't work over SSH. Using the manual flow Claude Code will print a URL; open it in any browser, complete login, then paste the returned code back into the terminal.
4. 403 / Model not available: Your account may not have access to the specific model Claude Code is requesting. Run /model inside a Claude session and select a model you have confirmed access to.
Fix 10: Run the Diagnostic Tool
When you're stuck and nothing above is obviously wrong, run:
claude doctor |
This prints a full diagnostic report Node version, PATH status, authentication state, TTY support, and more. It's the fastest way to identify what's actually broken in your specific environment, and you can paste the output directly into a support ticket.
Common Mistakes That Make Installation Harder
Using sudo npm install -g This is the most common mistake. It feels like a quick fix but creates a root-owned npm directory that will keep causing permission errors. Never use sudo with npm global installs.
Not reloading the shell after install Half of all "claude not found" complaints are solved by simply opening a new terminal window.
Using Git Bash on Windows PowerShell is required. Git Bash simply doesn't support the terminal features Claude Code needs.
Ignoring the Node version People install Claude Code on Node 14 or 16 and wonder why it crashes. Check your Node version first, every time.
Trying --force on stale lock errors The installer suggests using --force, but as documented in the official GitHub issue tracker, the flag doesn't actually work in this context. Manual lock file removal is the only fix.
Multiple installation methods mixed If you used curl first and then npm, you might have two installations conflicting. Clean up one before reinstalling.
Pro Tips for a Smooth Installation
Use the curl installer on Mac and Linux. It handles Node bundling, PATH setup, and permissions automatically. It's designed to avoid the common npm global install pitfalls:
bash curl -fsSL https://claude.ai/install.sh | bash |
Verify before you troubleshoot. Always run node -v, npm -v, and echo $PATH before assuming the tool itself is broken. 80% of install errors are environment issues, not Claude Code issues.
Add environment variables to your shell profile. Don't just export them for the current session. Any fix that requires an environment variable should go in ~/.zshrc or ~/.bashrc so it persists.
On Windows, make PATH changes permanent. Session-level PATH changes in PowerShell disappear when you close the window. Use System Properties → Environment Variables to make them stick.
Run claude doctor proactively. Don't wait until something breaks. Run it after installation to confirm everything is properly configured before you start a real project.
Real Use Case: From Repeated Failure to Working Install
Here's a realistic scenario based on issues reported across community forums and the official GitHub tracker.
The situation: A developer on macOS tried to install Claude Code three separate times. Each time, the installer said "Installation failed" and then confusingly "Installation complete." Running claude produced command not found. Restarting the machine changed nothing.
What went wrong: The first installation attempt was interrupted when macOS Gatekeeper killed the process. This left a stale lock file at ~/.local/state/claude/locks/2.0.71.lock. Every subsequent installation attempt detected this lock file and aborted but the contradictory success/failure messages masked what was actually happening.
The fix:
bash # Step 1: Find and remove the stale lock ls ~/.local/state/claude/locks/ rm ~/.local/state/claude/locks/2.0.71.lock # Step 2: Reinstall curl -fsSL https://claude.ai/install.sh | bash # Step 3: Open a new terminal and verify claude --version claude doctor |
Total time to fix once the cause was identified: under two minutes. The hard part was knowing what to look for.
Advanced Debugging Steps
If you've gone through every fix above and Claude Code still won't install, here's a more systematic approach:
1. Full environment check:
bash node -v # Must be 18+ npm -v # Must be recent echo $PATH # Check npm bin is included which npm # Where is npm actually located? npm config get prefix # Where does npm install global packages? |
2. Check for conflicting installations:
bash which claude # Is there an existing install somewhere? ls ~/.npm-global/bin/ # Is claude in your npm global bin? |
3. Clean slate reinstall:
bash # Uninstall existing npm uninstall -g @anthropic-ai/claude-code # Clear npm cache npm cache clean --force # Reinstall npm install -g @anthropic-ai/claude-code |
4. Check network access directly:
bash curl -I https://storage.googleapis.com |
If this fails, your network is blocking the download source.
5. Gather info for a support ticket:
bash claude doctor > claude-diagnostic.txt cat claude-diagnostic.txt |
Attach this file when contacting Anthropic support. It contains everything they need to help you.
FAQ: Claude Code Installation Failed
This contradictory message almost always means a stale lock file exists from a previous interrupted install. The installer aborts due to the lock but then partially completes a different step, giving you two contradictory status messages. Remove the lock file at ~/.local/state/claude/locks/ and reinstall.
Your terminal session hasn't loaded the updated PATH that the installer added to your shell config. Open a new terminal window, or run source ~/.zshrc (or ~/.bashrc on Linux). If that doesn't work, confirm that npm's global bin directory is actually in your PATH.
No and using sudo will likely cause more problems. Set your npm global directory to a user-owned path with npm config set prefix ~/.npm-global, add that to your PATH, and then install without sudo.
This happens in corporate environments that use SSL inspection. Export your company's CA certificate path: export NODE_EXTRA_CA_CERTS=/path/to/ca.pem. Your IT team can provide the certificate file.
A hanging installer almost always means a network block. The installer downloads from storage.googleapis.com. Set your proxy with export HTTPS_PROXY=http://your-proxy:port and retry, or ask IT to whitelist that domain.
Use PowerShell with npm install -g @anthropic-ai/claude-code. Don't use Git Bash; it lacks TTY support and will cause raw mode errors. If you're in WSL, use the curl installer within your Linux environment.
Run claude --version to confirm the binary is accessible, then run claude doctor for a full diagnostic report. Both should return clean results with no errors before you start using the tool in a real project.
Final Verdict
Claude Code installation failed errors are almost never caused by the tool itself being broken. In the vast majority of cases, the culprit is an environment issue: old Node.js, misconfigured npm permissions, a stale lock file, PATH not updated, or the wrong terminal on Windows.
The fix process is straightforward once you know what to look for:
Confirm Node.js 18+ is active
Never use sudo with npm global installs
Clear any stale lock files before retrying
Use PowerShell on Windows, not Git Bash
Reload your shell or open a new terminal after installing
Run claude doctor to diagnose anything that isn't obvious
Once past the installation hurdle, Claude Code is a genuinely powerful tool — it's worth the ten minutes it might take to sort out your environment. Follow this guide top to bottom, and you'll have it running.
Schema FAQ (Structured Data — 5 Questions)
json { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Why does Claude Code installation fail with a stale lock file error?", "acceptedAnswer": { "@type": "Answer", "text": "A stale lock file is left behind when a previous installation was interrupted. Remove it manually at ~/.local/state/claude/locks/ and then rerun the installer." } }, { "@type": "Question", "name": "What Node.js version is required for Claude Code?", "acceptedAnswer": { "@type": "Answer", "text": "Claude Code requires Node.js version 18 or later. Check your version with node -v and update using nvm install --lts if needed." } }, { "@type": "Question", "name": "How do I fix 'claude command not found' after installing Claude Code?", "acceptedAnswer": { "@type": "Answer", "text": "Open a new terminal window or run source ~/.zshrc (or ~/.bashrc on Linux) to reload your PATH. The installer adds the claude binary to your PATH config, but your current session needs to reload it." } }, { "@type": "Question", "name": "Can I install Claude Code on Windows?", "acceptedAnswer": { "@type": "Answer", "text": "Yes. Use Windows PowerShell — not Git Bash — and run npm install -g @anthropic-ai/claude-code. Git Bash lacks the TTY support Claude Code requires and will produce raw mode errors." } }, { "@type": "Question", "name": "How do I diagnose a Claude Code installation problem?", "acceptedAnswer": { "@type": "Answer", "text": "Run claude doctor from your terminal. It generates a full diagnostic report covering Node version, PATH, authentication, and TTY support. Attach this report when contacting Anthropic support." } } ] } |
Featured Snippet Answer
Question: How do I fix Claude Code installation failed?
Answer: To fix Claude Code installation failed, follow these steps: (1) Confirm you have Node.js 18 or later with node -v; (2) Remove any stale lock files at ~/.local/state/claude/locks/; (3) Avoid using sudo — fix npm permissions with npm config set prefix ~/.npm-global instead; (4) On Windows, use PowerShell instead of Git Bash; (5) After installing, open a new terminal or run source ~/.zshrc to reload your PATH; (6) Run claude doctor to get a full diagnostic report. The curl installer (curl -fsSL https://claude.ai/install.sh | bash) handles most of these issues automatically on Mac and Linux.