The error message "command not found: claude" or "bash: claude: command not found" is a frequent hurdle encountered when setting up the Claude Code CLI (Command Line Interface). This technical failure indicates that your operating system’s shell—whether it is Zsh, Bash, or PowerShell—cannot locate the executable file named claude within the directories defined in your system's PATH environment variable.

When you type a command into a terminal, the system does not search your entire hard drive for that program. Instead, it looks through a specific list of folders. If the Claude Code installation process placed the binary in a folder that isn't on that list, or if the terminal session has not been refreshed to recognize a newly added directory, the shell will return a "not found" error.

Resolving this issue requires a systematic approach to diagnostic checks, shell configuration updates, and occasionally, a clean reinstallation using the most reliable deployment methods provided by Anthropic.

Immediate Steps to Resolve the Claude Command Error

Before diving into complex configuration changes, several high-probability solutions can often resolve the issue in seconds.

Restart the Terminal Session

Terminal environments, particularly Zsh on macOS and Bash on Linux, load their configuration files (like .zshrc or .bashrc) only when a new session starts. If you just finished the installation process in an open window, that specific window does not yet "know" that the claude command exists.

Close all active terminal windows and tabs entirely. Reopen the terminal and attempt to run: claude --version

If the command works, the issue was simply a stale environment. If not, the binary is likely missing from your PATH.

Verify the Installation Path

You need to confirm where the Claude binary actually resides. Depending on the installation method used, Claude Code typically installs to one of the following locations:

  • Native Installer (Recommended): ~/.local/bin/claude
  • NPM Global Install: /usr/local/bin/claude or ~/.npm-global/bin/claude
  • Homebrew (macOS): /opt/homebrew/bin/claude

To check if the file exists at the most common location, run: ls -la ~/.local/bin/claude

If the terminal returns a "No such file or directory" error, the installation may have failed or was directed to a different prefix.

Understanding the PATH Environment Variable

To fix the "command not found" error permanently, one must understand how the PATH variable functions. The PATH is a colon-separated list of directories. When you run claude, the shell checks each directory in this list, from left to right, looking for an executable file with that name.

If you installed Claude Code via the recommended native script, the binary is usually placed in $HOME/.local/bin. In many default system configurations, especially on fresh macOS installs or specific Linux distributions like Ubuntu, this directory is not included in the default PATH.

Checking Your Current PATH

To see what your shell is currently looking at, execute: echo $PATH

You will see a long string of paths. If ~/.local/bin (or the full path like /Users/yourname/.local/bin) is missing from this output, the shell will never find Claude regardless of how many times you reinstall it.

Updating Shell Configuration for Zsh and Bash

Depending on your operating system and preferred shell, you will need to edit a specific configuration file to make the PATH change permanent.

Fix for Zsh (Default on macOS)

Modern macOS versions use Zsh. The configuration for this shell is stored in a hidden file in your home directory named .zshrc.

  1. Open the file in a text editor (like Nano or VS Code): nano ~/.zshrc
  2. Scroll to the bottom of the file and add the following line: export PATH="$HOME/.local/bin:$PATH"
  3. Save the file (in Nano, press Ctrl+O, Enter, then Ctrl+X).
  4. Apply the changes to your current session: source ~/.zshrc

Fix for Bash (Linux and Older macOS)

If you are using a Linux distribution or have manually switched to Bash, the configuration file is typically .bashrc or .bash_profile.

  1. Open the configuration file: nano ~/.bashrc
  2. Add the export line: export PATH="$HOME/.local/bin:$PATH"
  3. Save and exit.
  4. Reload the configuration: source ~/.bashrc

Handling the $HOME vs. Tilde (~) Distinction

A common mistake when editing shell profiles is using the tilde ~ inside quotes. While the shell often expands ~ to your home directory, it is safer and more robust to use the $HOME variable when defining paths in configuration files. This ensures that the path expands correctly across different environments and sub-shells.

Native Installer vs. NPM Global Installation

Anthropic provides two primary ways to install Claude Code. The choice of method significantly impacts why you might be seeing a "command not found" error.

The Case for the Native Installer

The native installer is currently the recommended method. It uses a shell script to fetch the appropriate binary for your architecture (Intel vs. Apple Silicon vs. Linux x64) and places it in a user-local directory.

MacOS/Linux Native Command: curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell) Native Command: irm https://claude.ai/install.ps1 | iex

The native installer is generally more reliable because it avoids the permission complexities associated with Node.js and npm. If you previously attempted an npm install and are getting errors, it is often best to uninstall the npm version and switch to the native script.

Troubleshooting NPM Installations

If you prefer using npm (Node Package Manager), the command is: npm install -g @anthropic-ai/claude-code

However, npm global installations often fail or lead to "command not found" errors due to two reasons:

  1. Permission Denied (EACCES): If you are forced to use sudo to install a global package, you are creating a situation where the binary might have root-only permissions, or the npm prefix is owned by the system rather than the user.
  2. NVM Mismatch: If you use NVM (Node Version Manager) to manage multiple Node.js versions, global packages are tied to the specific version of Node that was active during installation. If you install Claude while using Node v20 but your terminal switches to Node v22, the claude command will "disappear."

If you must use npm, ensure your npm global bin directory is in your path by running: npm config get prefix Then, add the /bin subdirectory of that output to your PATH.

Resolving Conflicts in VS Code and Integrated Terminals

A frequent complaint is that the claude command works in the standalone terminal (like Terminal.app or iTerm2) but fails within the Visual Studio Code integrated terminal.

Path Inheritance Issues

VS Code sometimes fails to inherit the full environment of your shell if the shell configuration is complex or if VS Code was launched from the GUI rather than the command line.

To fix this in VS Code:

  1. Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P).
  2. Search for "Terminal: Select Default Profile" and ensure it matches the shell you configured (e.g., Zsh).
  3. Restart VS Code completely.

VS Code Extension Environment

If you are using a Claude-related extension in VS Code that claims the "claude code command is not found," the extension may require a specific path to the binary. Check the extension settings and look for a "Path" or "Executable Location" field. You can find the exact path to provide by typing which claude in your working standalone terminal.

Using 'claude doctor' for Advanced Diagnostics

If the claude command is partially working or if you can access it by typing the full path (e.g., ~/.local/bin/claude --version) but the short command fails, Anthropic has provided a built-in diagnostic tool.

Run: claude doctor

This utility performs several checks:

  • Path Integrity: It verifies if the current directory is correctly mapped.
  • Authentication: It checks if your Anthropic API keys or session tokens are valid.
  • Version Check: It ensures you are not running an obsolete version of the CLI.
  • Dependency Check: It verifies that the local environment has the necessary permissions to read and write to the ~/.claude configuration directory.

If claude doctor identifies a path issue, it will often provide a specific snippet of code for you to copy and paste into your .zshrc or .bashrc.

Why Node.js Versions Matter

Claude Code requires Node.js version 18.0.0 or higher. Even if you use the native installer, the underlying logic often relies on a compatible Node environment being available on the system.

If you have an older version of Node installed, the claude command might fail silently or throw a "command not found" error if the installation script aborted prematurely due to version incompatibility.

To check your Node version: node --version

If the output is lower than v18, you should upgrade Node.js via Homebrew (brew upgrade node) or NVM (nvm install node --latest-npm).

Cleaning a Corrupted Installation

If you have tried modifying your PATH and restarting your terminal, but the error persists, your installation might be corrupted. A clean reinstall is the most efficient path forward.

  1. Remove existing folders: rm -rf ~/.claude
  2. Uninstall the NPM version (if applicable): npm uninstall -g @anthropic-ai/claude-code
  3. Run the Native Installer fresh: curl -fsSL https://claude.ai/install.sh | bash
  4. Confirm the binary is in the target folder: ls ~/.local/bin | grep claude

Summary of Fixes for Claude CLI

To resolve the "command not found: claude" error, follow this priority list:

  1. Refresh the Shell: Restart your terminal or run source ~/.zshrc.
  2. Check the Path: Ensure ~/.local/bin is in your $PATH variable.
  3. Use the Native Installer: Avoid npm if possible and use the official curl script.
  4. Verify Permissions: Ensure you didn't use sudo for installation, which can cause permission-based access issues.
  5. Check Node.js: Ensure your system has Node.js 18+ installed and accessible.

FAQ

What does "zsh: command not found: claude" mean on a Mac?

It means the Zsh shell looked through all the folders in its search list and did not find the claude executable. This is usually because the folder ~/.local/bin isn't in your .zshrc file's PATH definition.

Can I run Claude Code without adding it to the PATH?

Yes. You can run it by providing the full path to the binary. For example: /Users/yourusername/.local/bin/claude. However, this is inconvenient for daily use, so adding it to the PATH is highly recommended.

Why did Claude work yesterday but not today?

This often happens if you installed Claude via NVM and changed your Node.js version, or if you modified your .zshrc file and accidentally deleted the export PATH line. Another possibility is that you are using a different terminal app that uses a different shell (e.g., switching from Zsh to Bash).

How do I fix the error on Windows WSL?

If you are using WSL (Windows Subsystem for Linux), you should treat the environment as a Linux system. Use the native Linux install script and add the path to your .bashrc or .zshrc inside the WSL terminal, not the Windows PowerShell environment.

Does "command not found" mean the installation failed?

Not necessarily. In most cases, the installation succeeded, but the "link" between the binary's location and the terminal's search path was never established. If the file exists in ~/.local/bin/claude, the installation was successful.