Claude Code Complete Guide

Fix "claude is not recognized" / PowerShell cmdlet / command not found

For / Key Points

For: Anyone who installed Claude Code but gets an error when running the claude command

Key Points:

• In most cases, the cause is a missing PATH configuration
• This guide provides OS- and shell-specific verification steps and fix commands
• The official installer typically handles PATH setup automatically

You typed claude and the terminal threw an error. The installation succeeded, but your shell has no idea where to find it. This guide gets you past that error in minutes.

Exact Windows PowerShell error?

If your error is claude : The term 'claude' is not recognized as the name of a cmdlet, start with Claude Code Windows Install Guide. That article covers the native Windows installer, %USERPROFILE%\.local\bin, and the Git Bash / PowerShell tool choice.

Identify Your Error

Check the error message you received. While these errors look different, PATH misconfiguration is the most common cause — the shell cannot locate the claude binary because the install directory is not in your PATH.

Shell	Error Message
PowerShell	claude : The term 'claude' is not recognized as the name of a cmdlet, function, script file, or operable program.
CMD	'claude' is not recognized as an internal or external command, operable program or batch file.
bash / zsh	claude: command not found

Other causes are possible — a failed installation, confusing Windows with WSL, or npm global path issues. But PATH is the first thing to check.

Quick 1-Minute Check

If you are short on time, follow this sequence first.

1. Run claude --version
2. If it fails, run where claude (Windows) or which claude (macOS / Linux)
3. Not found — reinstall with the official installer
4. Found but cannot run — suspect a PATH propagation or shell restart issue
5. Using WSL? — confirm which environment you installed in and which you are running from

In most cases, the fix is straightforward: locate the claude binary and add its directory to PATH if needed. However, if the installation itself is broken, reinstalling with the official installer is faster than fixing PATH manually.

Why PATH Issues Prevent claude from Being Found

When you type a command, the terminal searches directories listed in the PATH environment variable in order. If the directory containing claude is not in PATH, the shell reports "command not found" — even though the binary exists on your machine.

This means the actual cause falls into one of two patterns:

• claude is installed, but its directory is not in PATH
• claude was not installed in the expected location

This guide walks through both scenarios.

Fix 1: Reinstall with the Official Installer (Fastest)

Try reinstalling with the official installer before manually fixing PATH. The installer typically handles binary placement, PATH configuration, and version alignment in one step.

Windows

Open PowerShell and run:

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

Using CMD instead of PowerShell?

irm is a PowerShell command. If you see "'irm' is not recognized" in CMD, switch to PowerShell or use this CMD command instead:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

macOS / Linux

Open your terminal and run:

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

After installation, close the terminal and open a new one. PATH changes only take effect in new shell sessions.

# Verify in a new terminal
claude --version

If this fixed the issue, you are done. If the error persists, continue to the next section.

Fix 2: Manually Configure PATH

If you cannot use the official installer or installed via npm, you need to set PATH manually.

Locate the claude Binary

First, find where claude was installed.

# macOS / Linux
which claude 2>/dev/null || find ~/.local/bin ~/.npm-global/bin ~/bin -name "claude" 2>/dev/null

# Windows PowerShell
Get-Command claude -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
# If not found, check directly
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

Common install locations are listed below. The actual path may vary depending on your OS, shell, installation method, and version. Use the table as a starting point for your search.

Installation Method	Typical Location
Official installer	~/.local/bin/claude etc.
npm global install	$(npm config get prefix)/bin/claude etc.
Windows	%USERPROFILE%\.local\bin\claude.exe etc.

Windows: PowerShell / CMD

The following adds the path to your user-level PATH environment variable. Check whether the path is already registered before adding to avoid duplicates.

# 1. Check user PATH (persistent setting)
[Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::User) -split ";" |
  Where-Object { $_ -like "*.local*" }

# 2. Check current session PATH
$env:PATH -split ";" | Where-Object {$_ -like "*.local*"}

# 3. If empty, add it permanently
[Environment]::SetEnvironmentVariable(
    "PATH",
    "$env:PATH;$env:USERPROFILE\.local\bin",
    [EnvironmentVariableTarget]::User
)

# 4. Apply to current session immediately
$env:PATH = "$env:PATH;$env:USERPROFILE\.local\bin"

# 5. Verify
claude --version

Installed via npm?

With npm global install, claude may be placed under the npm global prefix directory rather than .local\bin.

First, check the prefix:

npm config get prefix

Then add that directory (or its binary subdirectory) to PATH as needed.

Note: npm installation is still supported as an advanced installation option¹. For new Windows installs or reconfiguration, the official native installer is usually simpler.

macOS (zsh)

# 1. Check if .local/bin is in PATH
echo $PATH | tr ':' '\n' | grep local

# 2. If not present, add to .zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# 3. Apply to current session
source ~/.zshrc

# 4. Verify
claude --version

Linux (bash)

# 1. Check if .local/bin is in PATH
echo $PATH | tr ':' '\n' | grep local

# 2. If not present, add to .bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# 3. Apply to current session
source ~/.bashrc

# 4. Verify
claude --version

npm PATH issue (macOS / Linux)

If you installed via npm globally and get command not found, the bin directory under the npm prefix may not be in your PATH.

First, check the prefix:

npm config get prefix

Then add $(npm config get prefix)/bin to PATH if needed.

# bash example
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Fix 3: Run Temporarily with npx

If you want to skip PATH configuration entirely, npx runs Claude Code without a global install.

npx @anthropic-ai/claude-code

This works without PATH setup but is slower on each launch. For regular use, apply Fix 1 or Fix 2.

Diagnose with claude doctor

Claude Code includes a built-in diagnostic command. Use it when claude runs but behaves unexpectedly.

claude doctor

The exact output varies by environment and version, but claude doctor serves as a diagnostic tool for checking installation state and common configuration problems.

For example, it can help verify:

• Installation type (native / npm)
• Version information
• Common configuration issues

Common Pitfalls

Not Restarting the Terminal

The most frequent oversight. Even after the installer configures PATH, existing terminal windows do not pick up the change. Always open a new terminal window.

Confusing CMD and PowerShell on Windows

The official install command irm https://claude.ai/install.ps1 | iex is PowerShell-only. Running it in CMD (Command Prompt) produces "'irm' is not recognized."

Mixing Up WSL and Windows

When using WSL2, the Linux environment inside WSL and the Windows host have separate PATH variables. If you installed inside WSL, use claude inside WSL. It will not be recognized in Windows PowerShell, and vice versa.

Auto-Update Breaking PATH

GitHub Issues includes reports of PATH inconsistencies on Windows after auto-updates². If you experience the same symptom, reinstalling with the official installer is often faster than manually tracing the PATH.

Still Not Working?

If none of the above resolves your error, check the following:

• Node.js version (npm installs only): npm installation may fail if the required Node.js version is not met³
• Disk space: Ensure sufficient free space for installation and updates
• OS boundary: Confirm you are not confusing Windows host, WSL, and remote environments
• GitHub Issues: Search anthropics/claude-code for similar symptoms

The error message looks intimidating, but this type of issue typically resolves with a terminal restart, PATH update, or reinstallation. Start with the official installer, then check PATH if needed — this order minimizes detours.

Summary

If claude is not recognized, treat it as a PATH and environment-boundary problem first. On Windows, verify the native installer path and the terminal session; on WSL, macOS, and Linux, verify the shell-specific PATH. Reinstalling with the official installer is usually faster than debugging a broken global package setup.

Related Articles

• Claude Code Installation Guide — First-time installation steps
• Claude Code Windows Native Installation — Windows-specific details
• Claude Code Troubleshooting Guide — Other error solutions

---

1. Claude Code Docs - Advanced setup — npm install is supported under advanced installation options ↩

2. GitHub Issue #32583 - Claude Desktop auto-update breaks PATH on Windows ↩

3. Claude Code Docs - Advanced setup — npm installation requires Node.js 18 or later ↩