Claude Codeでcommand not found: claudeが出たらPATHを通す手順

command not foundはPATHが原因

zsh: command not found: claudeやbash: claude: command not foundは、シェルがコマンドを探す場所の一覧(PATH)に~/.local/binが入っていないときに出ます。macOSのzshなら、次の2行でパスが通ります。

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

bashは~/.zshrcを~/.bashrcに、Windowsはユーザー環境変数への追加に読み替えます。

ネイティブインストーラーはclaude本体をmacOS/Linuxでは~/.local/bin/claude、Windowsでは%USERPROFILE%\.local\bin\claude.exeに配置します。新しいディレクトリをPATHに反映するには、シェル設定への追記かターミナルの再起動が必要です。インストーラー自身も、この状態を検出すると出力のSetup notes:にNative installation exists but ~/.local/bin is not in your PATH.と表示します。ただしPATH自体は書き換えません。

エラーの出方はプラットフォームごとに違います。

この症状は手元で再現できます。v2.1.287が入ったmacOSで、PATHを/usr/bin:/binだけに絞ったシェルからclaudeを呼ぶと、次のとおりになります。

env -i PATH=/usr/bin:/bin /bin/zsh -c 'claude --version; echo "exit=$?"'
env -i PATH=/usr/bin:/bin /bin/bash -c 'claude --version; echo "exit=$?"'

出力はzsh:1: command not found: claudeと/bin/bash: claude: command not foundで、どちらも終了コードは127でした。127はシェルがコマンドを見つけられなかったときの値です。CIや自作スクリプトでclaudeを呼ぶ場合、終了コードが127ならPATHの問題、それ以外の非ゼロならclaudeが起動したうえでの失敗、と最初に切り分けられます。

どこから手を付けるかを決める

command not foundの裏には、PATH未設定のほかにも原因が隠れています。最初の1分で次の順に確認すると、読むべき節が決まります。

PATHに~/.local/binを足す

まず、インストール先のディレクトリがすでにPATHに入っているかを確認します。

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

パスが1行出力されればPATHに入っています。何も出力されない場合は、シェルの設定ファイルに追記します。上の再現環境でこの確認をすると、何も表示されずgrepの終了コードは1でした。そこでexport PATH="$HOME/.local/bin:$PATH"を実行してからclaude --versionを呼ぶと、2.1.287 (Claude Code)が返り、which -a claudeは~/.local/bin/claudeを1行だけ返しました。追記後の期待値はこの形です。

どのファイルに書くかはシェルとOSで変わります。

Zshは冒頭の2行を実行し、続けてclaude --versionでバージョンが出るかを確かめます。Bashは追記先を上の表のファイルに替えるだけです。

macOSのBashで~/.bash_profileが無く、~/.bash_loginか~/.profileだけがある環境では、後者のファイルに書きます。~/.bash_profileを新規に作ると、既存のファイルが読まれなくなるためです。追記したのに新しいターミナルで直らないときは、書いたファイルがログインシェルの読み込み対象かどうかを疑ってください。~/.bashrcにだけ書いた設定は、~/.bash_profileからsource ~/.bashrcしていない限り、macOSのTerminalでは反映されません。

fishやNushellのような他のシェルでは、それぞれの設定構文に合わせて~/.local/binを追記し、ターミナルを再起動します。fishでの具体的なコマンドはClaude CodeでfishシェルのPATHを通す設定と注意点にまとめています。BashツールがfishのconfigやAbbreviationを読み込まない注意点も同じ記事で扱っています。

Windowsでは、シェルによってPATH確認のコマンドが異なります。PowerShellでは次を実行します。

$env:PATH -split ';' | Select-String '\.local\\bin'

出力がなければ、ユーザーPATHに%USERPROFILE%\.local\binを追加します。

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

コマンドプロンプト(CMD)の場合はecho %PATH% | findstr /i "local\bin"で確認し、出力がなければシステム設定の環境変数からUser PATHに%USERPROFILE%\.local\binを追加します。Windowsではいずれの方法でも、変更後にターミナルを再起動しないと反映されません。インストールした直後のセッションは古いPATHを保持したままです。

複数のインストールが競合していないか確認する

PATHを直しても解決しない場合、複数のインストールが競合している可能性があります。claudeはネイティブインストーラー・レガシーなローカルnpmインストール・グローバルnpmインストールの3箇所から入る可能性があります。古いものが優先されると、PATHを直したように見えても実行されるのは別バージョンです。

which -a claude

このコマンドはPATH上に見つかるclaudeバイナリをすべて列挙します。何も出力されない場合はまだPATHに何も無い状態なので、前の節の確認からやり直します。複数出力される場合は、3つの候補を個別に確認します。

ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null

手元の環境(ネイティブインストールのみ)では、1行目が~/.local/bin/claude -> ~/.local/share/claude/versions/2.1.287というシンボリックリンクを示しました。2行目はNo such file or directoryでした。これはエラーではなく、その場所に何も無いという意味です。各行の見方は次のとおりです。

過去に一度でもClaude Codeを導入したMacやLinuxでは、~/.claude/local/に古いバイナリが残ったまま、現在は気づかずネイティブインストーラーで入れ直していることがあります。PATHの優先順位次第では、新しく入れたはずの方ではなくこちらが先に見つかります。その場合はcommand not foundではなく、古い機能しか使えない、バージョン番号が更新されない、という別の症状として現れます。asdfでNode.jsを管理している環境では、この3経路よりさらに外側にあるshimが同じ症状を起こすこともあります。詳しくはasdfのshimでClaude Codeが古いバージョンを掴み続ける問題の直し方にまとめました。

which -aはPATH上の実行ファイルしか拾いません。シェルのaliasや関数がclaudeを横取りしている場合は、type -a claudeで見つかります。実際にclaudeというaliasを定義したZshでtype -a claudeを実行すると、claude is an alias for echo old-claudeと、実体の~/.local/bin/claudeの両方が列挙されました。claude updateとclaude doctorは、古いclaudeのaliasを設定ファイルから探します。対象は~/.zshrc・~/.bashrc・~/.config/fish/config.fishです。macOSでは~/.bash_profile・~/.bash_login・~/.profileのうち最初に存在する1つも対象になります。ZDOTDIRを設定している場合は$ZDOTDIR/.zshrcが対象です。昔の導入手順で書いたaliasは、設定ファイルを開いて探す価値があります。

複数見つかった場合は1つに絞ります。macOS/Linuxで推奨されるのは~/.local/bin/claudeのネイティブインストールです。余分な経路は削除します。

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local

macOSでHomebrewから入れた場合は、brew uninstall --cask claude-codeで削除します。claude-code@latestのcaskで入れたなら、名前を差し替えてください。

Windowsでも同じ考え方で競合を確認できます。PowerShellで次を実行すると、PATH上に見つかるclaudeをすべて列挙します。

where.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

複数のインストールが見つかった場合、npmグローバルインストールはnpm uninstall -g @anthropic-ai/claude-codeで、WinGetインストールはwinget uninstall Anthropic.ClaudeCodeで削除し、ネイティブインストーラーによる1つだけに絞ります。レガシーなローカルnpmインストールが残っている場合は、Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"で削除します。

Windowsで見つからない・別のアプリが開くとき

Windowsには、PATHを直しても解決しない固有の原因が2つあります。

1つ目は、claudeと打つとCLIではなくClaude Desktopが起動する症状です。古いバージョンのClaude Desktopをインストールしていると、WindowsAppsディレクトリにClaude.exeが登録され、PATH上でClaude Code CLIより優先されることがあります。Claude Desktopを最新版に更新すると解消します。

2つ目は、Claude Codeの更新直後に'claude' is not recognizedが出る症状です。このときは、PATHを疑う前に%USERPROFILE%\.local\binにclaude.exeが残っているかを見ます。Windowsでの更新は、既存のclaude.exeをバックアップ名に変えてから新しいファイルを移す手順で進みます。移動に失敗し、バックアップを元の名前に戻す処理まで失敗すると、ディレクトリにはバックアップだけが残ってclaude.exeが無い状態になります。バックアップはclaude.exe.old.に数字のタイムスタンプが続く名前なので、最新のものを戻せば復旧します。

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

この場合の見分け方は単純で、Test-PathがFalseを返し、.local\binの一覧にclaude.exe.old.で始まるファイルがあれば該当します。ディレクトリ自体がPATHに無いのなら、前の節のPATH追加が先です。

VS Code拡張機能だけ入れている場合は空振りする

VS Code拡張機能は、拡張機能自身のチャットパネル用にCLIのプライベートコピーを内蔵しているだけで、~/.local/binには何も置きません。拡張機能だけを入れた状態では~/.local/bin/claude自体が存在しないため、PATHをいくら見直しても解決しません。ターミナルからclaudeコマンドを使いたい場合は、拡張機能とは別にスタンドアロンインストールが必要です。

修正後にバイナリが正しく動くか確認する

PATHを直したら、バージョンが表示されるかで確認します。

claude --version

2.1.287 (Claude Code)のようにバージョン番号が表示されれば直っています。ここでまだcommand not foundと出る場合、コマンドを実行したターミナルウィンドウ自体を新しく開き直してください。インストール元のセッションは古いPATHを保持したままのことがあります。

claude --versionは動くのにclaude本体がクラッシュしたり起動時に固まったりする場合は、原因はもうPATHではありません。バイナリの実体と実行権限を確認します。

ls -la "$(command -v claude)"

手元の環境では、~/.local/bin/claudeがバージョン別ディレクトリへのシンボリックリンクとして表示されました。リンク先が存在しない場合や、実行ビットが立っていない場合はここで分かります。

Linuxでは、共有ライブラリの不足も起動時のクラッシュの原因になります。

ldd "$(command -v claude)" | grep "not found"

不足しているライブラリが表示された場合、システムのパッケージマネージャーで該当パッケージを追加します。Alpine Linuxのようなmuslベースのディストリビューションでは、標準ではbashやcurlすら入っていません。インストール用にbashとcurl、実行時にlibgcc・libstdc++・ripgrepを別途入れる必要があります。

glibcの環境なのにlibstdc++.so.6やlibgcc_s.so.1の読み込みエラーが出る場合は、インストーラーが誤ってmusl向けのバイナリを選んだ可能性があります。musl向けのクロスコンパイル用パッケージが入っている環境で起こりうる、と公式に記載があります。ldd --version 2>&1 | head -1の出力にGNU libcかGLIBCとあればglibc、muslとあればmuslです。glibcなのにmusl版が入っていたなら、削除して入れ直します。

WSLで見つからない・実行できない

WSLでは、メッセージによって原因が異なります。command not foundならPATHの問題で、WSLの中で上記のLinux向けの手順を実施します。claudeはPowerShellやCMDからではなく、WSLのターミナルの中でインストールして起動します。

一方、cannot execute binary file: Exec format errorはPATHの問題ではありません。WSL1で起きる既知の不具合で、GitHubのissue #38788で追跡されています。確実な解決策はディストリビューションのWSL2への変換で、PowerShellからwsl --set-version <DistroName> 2を実行します。WSL1のまま使いたい場合の回避策も公式のトラブルシューティングにあります。

npmでインストールしたWSL環境では、exec: node: not foundが出ることがあります。WSLがWindows側のNode.jsを使っている可能性があるので、which nodeの出力が/mnt/c/で始まっていないかを確認します。Linuxのバイナリなら/usr/などで始まります。WSLはWindowsのPATHを既定で取り込むため、WindowsのnvmがWSLのnvmより優先されることもあります。

それでも直らないときの次の一手

ここまでの手順で直らない場合、原因はPATH以外にあります。ネットワーク・証明書・権限エラーなど、インストール時の他のエラーメッセージから原因を切り分けたい場合はClaude Codeインストールエラーの切り分けチェックリストを、そもそもの導入手順を最初から見直したい場合はClaude Code install完全ガイドを確認してください。Windows固有の詳しい導入手順はClaude Code Windowsインストールにまとめています。

権限エラーでインストール先に書き込めない場合、公式のトラブルシューティングは~/.local/binを作成したうえでsudo chown -R $(whoami) ~/.localで所有者を自分に直す手順を案内しています。sudoを付けてclaudeを実行してもPATHの検索先は増えません。npmのインストールにsudoを使うことは、WSLの項で公式が明確に避けるよう書いています。

まとめ

切り分けで迷ったら、インストールのやり直しより先にPATHを疑うのが安上がりです。複数の入れ方を試した環境では、残したい1つ以外を消してから設定ファイルを直すと、同じ症状が戻りにくくなります。