Claude Code « command not found » : corriger l'erreur d'installation et de PATH

Vous avez installé Claude Code, mais taper claude dans le terminal donne ceci — ça vous parle ?

zsh: command not found: claude                                         # macOS
bash: claude: command not found                                        # Linux
'claude' is not recognized as an internal or external command         # Windows CMD
claude : The term 'claude' is not recognized as the name of a cmdlet   # PowerShell

Cette erreur signifie « l'exécutable claude est introuvable », et la cause est presque toujours « le dossier d'installation n'est pas dans votre PATH ». L'installation elle-même a souvent réussi — le shell ne sait simplement pas où chercher. Cet article couvre les méthodes et emplacements d'installation, la correction du PATH, les conflits entre plusieurs installations, les pièges propres à Windows et la mise à jour — le tout vérifié dans la documentation officielle au 29 septembre 2026.

Les points clés d'emblée. (1) command not found n'est presque toujours que « ~/.local/bin (le dossier d'installation) n'est pas dans le PATH » — ajoutez-le, redémarrez le terminal et tout fonctionne. (2) Une erreur de permission npm (EACCES) ne doit PAS être corrigée avec sudo — passez plutôt à l'installeur natif. (3) En cas de blocage, lancez claude doctor — il vérifie d'un coup l'état de l'installation, les réglages et le résultat de la mise à jour. Les commandes exactes et les valeurs par défaut évoluent selon la version, alors vérifiez les dernières dans la documentation officielle.

1. Ce que cette erreur vous dit vraiment

Lorsque vous tapez une commande, le shell (zsh / bash / PowerShell) parcourt dans l'ordre les dossiers listés dans la variable d'environnement PATH et exécute le premier exécutable correspondant. command not found: claude signifie qu'aucun de ces dossiers ne contenait claude.

L'important : cela ne veut pas forcément dire que l'installation a échoué. L'installeur natif place claude dans ~/.local/bin (Windows : %USERPROFILE%\.local\bin), mais si ce dossier n'est pas dans le PATH, le binaire existe sans que le shell puisse le trouver. Ainsi, la plupart des cas se règlent en « ajoutant une ligne au PATH et en redémarrant le terminal ». Avant de soupçonner un échec d'installation, lancez ls ~/.local/bin/claude pour vérifier si le binaire est bien présent.

Sous Windows, une « mauvaise console » pour la commande d'installation (par exemple, exécuter la commande PowerShell dans CMD) produit des erreurs différentes — abordées au §4. Commençons par bien fixer les méthodes et emplacements d'installation corrects.

2. Méthodes d'installation et emplacement du binaire

Voici les méthodes d'installation indiquées sur la page officielle d'installation au 29 septembre 2026, et l'endroit où le binaire atterrit (l'installeur natif est recommandé).

L'essentiel : l'installeur natif est officiellement recommandé. La version npm installe le même binaire natif. Depuis la v2.1.198, le paquet npm exige Node.js 22 ou plus récent, mais avec un Node.js plus ancien, npm affiche seulement un avertissement EBADENGINE et l'installation se termine quand même (le binaire n'utilise pas Node pour s'exécuter). La voie npm est plus sujette aux problèmes de permissions et de PATH : pour une nouvelle installation, le natif est le choix sûr. À noter qu'installer uniquement l'extension VS Code embarque un CLI privé dans l'extension et n'ajoute PAS claude au PATH — si vous voulez claude dans le terminal, installez-le séparément.

3. Principales causes et solutions

Voici les causes fréquentes autour de command not found, associées à leurs solutions.

Un exemple concret de correction du PATH (macOS zsh) : echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc puis source ~/.zshrc. Sous Linux bash, faites de même dans ~/.bashrc ; pour bash sous macOS, utilisez ~/.bash_profile (le Terminal lance bash comme shell de connexion, qui ignore ~/.bashrc). Dans Windows PowerShell, ajoutez le dossier au PATH utilisateur avec [Environment]::SetEnvironmentVariable('PATH', "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin", 'User'). Après le changement, ouvrez un nouveau terminal et vérifiez avec claude --version.

« Native installation exists but ~/.local/bin is not in your PATH »

Cet avertissement apparaît dans la sortie de claude doctor (sous « Installation warnings ») et sous la zone de saisie. Voici son texte, tel que des utilisateurs l'ont cité dans les issues GitHub officielles :

Native installation exists but ~/.local/bin is not in your PATH
Run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then open a new terminal or run: source ~/.zshrc

Il signifie que le binaire natif se trouve dans ~/.local/bin, mais que ce dossier est absent du PATH que voit Claude Code. La correction est celle ci-dessus : ajoutez la ligne au fichier de configuration de votre shell et ouvrez un nouveau terminal. Si echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin" affiche déjà le dossier dans un nouveau terminal et que l'avertissement persiste, vous êtes dans un cas signalé sur GitHub (#63695 : PATH défini seulement dans ~/.zshenv et lancement depuis le terminal de VS Code ; #75431 : claude installé ailleurs). Les deux ont été fermés sans correctif au 29 septembre 2026. Si claude --version fonctionne dans un nouveau terminal, l'installation elle-même est correcte.

4. Pièges propres à Windows

Sous Windows, l'échec classique consiste à exécuter la commande d'installation dans la « mauvaise console ». L'erreur affichée indique de quelle confusion il s'agit.

Autres remarques Windows : (1) Redémarrez le terminal après l'installation (un changement de PATH ne prend effet que dans un nouveau terminal). (2) Un ancien Claude Desktop qui a enregistré WindowsApps\Claude.exe peut faire lancer l'application de bureau au lieu du CLI quand vous tapez claude — mettez Claude Desktop à jour. (3) Git for Windows est facultatif : sans lui, Claude Code exécute les commandes via son outil PowerShell. Si Git est installé mais que Git Bash reste introuvable, pointez CLAUDE_CODE_GIT_BASH_PATH dans les réglages vers votre bash.exe. Exécuter sous WSL est aussi une option.

VS Code : « Could not locate the Claude CLI on PATH »

L'extension VS Code affiche ce message sous Windows quand vous ouvrez Claude Code dans le terminal intégré, que le shell de ce terminal est PowerShell et que l'extension ne trouve pas le claude installé dans le PATH. Le message commence ainsi :

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH.

L'extension bloque le lancement parce qu'appeler claude par son nom dans PowerShell pourrait exécuter un claude du dossier ouvert au lieu du CLI installé. (1) Ouvrez une nouvelle fenêtre PowerShell en dehors de VS Code et lancez where.exe claude ; si rien ne s'affiche, ajoutez le dossier d'installation au PATH comme au §3. (2) Placez l'entrée PATH dans une variable d'environnement utilisateur ou système, pas seulement dans votre profil PowerShell (l'extension n'exécute pas votre profil). (3) Redémarrez VS Code, car il ne lit le PATH qu'au démarrage.

« 'claude' is not recognized » juste après une mise à jour

Pour se mettre à jour sous Windows, Claude Code renomme le claude.exe existant en une sauvegarde nommée claude.exe.old. suivie d'un horodatage, puis met la nouvelle version en place. Si ce déplacement échoue et que le renommage ne peut pas être annulé, %USERPROFILE%\.local\bin garde la sauvegarde mais plus de claude.exe. Restaurez la sauvegarde la plus récente dans PowerShell :

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

Vérifiez ensuite avec claude --version. S'il n'y a aucun fichier claude.exe.old.*, réinstallez avec irm https://claude.ai/install.ps1 | iex. Depuis la v2.1.281, une mise à jour ratée restaure automatiquement l'exécutable sauvegardé.

5. Mise à jour automatique et manuelle

Les installations natives se mettent à jour automatiquement en arrière-plan et prennent effet au prochain lancement. Pour mettre à jour manuellement, utilisez claude update ; pour réinstaller/figer une version précise, utilisez claude install <version> (accepte aussi stable / latest). Le résultat de la dernière tentative de mise à jour s'affiche avec claude doctor. Les installations via Homebrew, WinGet, apt, dnf et apk ne se mettent pas à jour seules par défaut ; avec Homebrew et WinGet, définir CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 fait lancer la mise à niveau par Claude Code.

« Auto-update failed · Run claude doctor »

Quand une mise à jour en arrière-plan échoue, une session en cours l'affiche dans sa zone d'état. Les issues GitHub citent deux formulations : Auto-update failed · Run claude doctor (de la v2.1.220 à la v2.1.278) et, sur des installations npm de versions plus anciennes, Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code. Procédez dans cet ordre :

1. Lancez claude doctor dans un terminal — il montre le résultat de la dernière tentative de mise à jour et les éventuels avertissements d'installation.
2. Lancez claude update pour appliquer la mise à jour tout de suite. Il répond Successfully updated from <old version> to version <new version>, ou Claude Code is up to date (<version>) s'il n'y a rien à installer.
3. Si vous êtes déjà à jour, l'échec était passager (par exemple une coupure réseau). D'après les issues GitHub (#89286, #96038), l'avis peut rester affiché jusqu'au redémarrage de la session.
4. Sur une installation npm globale dont le dossier n'est pas accessible en écriture, la mise à jour auto ne peut pas fonctionner — passez à l'installeur natif (voir l'encadré ci-dessus).
5. Si l'échec se répète sur un réseau d'entreprise, vérifiez que downloads.claude.ai est joignable.

6. La démarche de diagnostic

Quand la cause n'est pas claire, procédez du haut vers le bas. La plupart des cas se résolvent dès l'étape 3.

Conclusion

Le « command not found: claude » de Claude Code n'est, dans la plupart des cas, que « le dossier d'installation (~/.local/bin) n'est pas dans le PATH ». Le binaire existe, alors ajoutez une ligne au PATH, redémarrez le terminal et tout fonctionne. Pour l'installation, l'installeur natif est recommandé (la version npm demande Node.js 22+ et comporte davantage de pièges de permissions/PATH). Une erreur EACCES de npm se corrige en passant au natif, pas avec sudo.

Diagnostiquez avec (1) claude doctor -> (2) which -a claude / where.exe claude pour les conflits -> (3) ajout de ~/.local/bin au PATH -> (4) suppression des versions superflues -> (5) réinstallation native. Sous Windows, attention à la confusion de console (par exemple irm dans CMD), à la nécessité de redémarrer le terminal, et à l'ancien conflit Claude Desktop Claude.exe. Mettez à jour avec claude update / claude install, et arrêtez la mise à jour auto avec DISABLE_AUTOUPDATER. En cas de blocage, une réinstallation native est la solution fiable. À lire aussi : le récapitulatif des erreurs Claude Code, les erreurs d'authentification / connexion.

FAQ

Q. Je l'ai installé, mais j'obtiens command not found: claude.
A. Presque à coup sûr, le dossier d'installation n'est pas dans votre PATH. Vérifiez d'abord si le binaire existe avec ls ~/.local/bin/claude (Windows : %USERPROFILE%\.local\bin) ; s'il est là, ajoutez export PATH="$HOME/.local/bin:$PATH" à ~/.zshrc/~/.bashrc puis ouvrez un nouveau terminal. L'installation elle-même a généralement réussi.

Q. npm install -g échoue avec une erreur de permission (EACCES).
A. N'utilisez pas sudo npm (officiellement déconseillé ; cela attire les problèmes de permissions et de sécurité). Le plus rapide et le plus sûr est de passer à l'installeur natif (mac/Linux : curl -fsSL https://claude.ai/install.sh | bash). La build native n'a aucun piège de permission et ne nécessite pas Node. Vous pouvez aussi déplacer le prefix global de npm vers un dossier accessible en écriture par l'utilisateur, mais la recommandation officielle est le natif.

Q. J'ai plusieurs installations de claude et c'est une ancienne version qui s'exécute.
A. Lancez which -a claude (Windows : where.exe claude) pour voir tous les claude présents dans le PATH. Vous avez peut-être un mélange de npm-global, Homebrew, WinGet et natif. Gardez la version native (~/.local/bin) et supprimez les autres (par exemple npm uninstall -g @anthropic-ai/claude-code) pour n'avoir plus qu'une seule installation.

Q. Sous Windows, taper claude ouvre l'application de bureau.
A. Un ancien Claude Desktop a enregistré WindowsApps\Claude.exe, et il a la priorité sur le CLI dans le PATH. Mettez Claude Desktop à jour pour résoudre cela. De plus, si après l'exécution de l'installeur PowerShell il reste introuvable ou affiche une ancienne version, redémarrez le terminal pour que le changement de PATH prenne effet.

Q. Les mises à jour ne fonctionnent pas / je veux les arrêter.
A. Les installations natives se mettent à jour automatiquement en arrière-plan et prennent effet au prochain lancement. Manuellement, utilisez claude update ; pour réinstaller/figer, claude install <version>. Si Auto-update failed · Run claude doctor s'affiche, lancez claude doctor puis claude update ; s'il indique que vous êtes à jour, redémarrer la session fait disparaître l'avis. Si la mise à jour auto échoue sur une installation npm globale, c'est un problème de permission d'écriture — suivez claude doctor et migrez vers le natif. Pour arrêter la mise à jour auto, définissez DISABLE_AUTOUPDATER dans la section env des réglages ; pour bloquer toutes les mises à jour, définissez DISABLE_UPDATES.