Installer Claude Code : Native vs npm, corriger le PATH et premier lancement

Pour une installation native (Native Install) de Claude Code, l’environnement d’exécution Node.js n’est aucunement requis. L’installateur npm nécessite actuellement Node.js 22+, mais le binaire installé fonctionne de manière totalement autonome sans le runtime Node. La documentation officielle d’Anthropic recommande explicitement d’utiliser l’installation Native (pour plus de détails, consultez le guide d’installation). Pour utiliser cet agent de code dans votre terminal, vous devez choisir une méthode d’installation, exécuter la commande appropriée dans un interpréteur pris en charge et vous assurer que l’exécutable est correctement reconnu par votre système d’exploitation. Lorsque des erreurs d’appel de commande surviennent, identifier la cause racine dépend de la distinction entre une distribution binaire autonome et une installation via gestionnaire de paquets.

Native vs npm : frontières architecturales et rôle de Node.js

La documentation officielle d’Anthropic recommande l’installation Native (guide d’installation). Dans cette configuration, l’environnement d’exécution Node.js est superflu : l’installateur télécharge un binaire autonome précompilé qui n’interagit jamais avec Node pendant son exécution.

L’installation via le paquet global npm reste une alternative disponible. Actuellement, l’installateur npm exige Node.js 22 ou une version ultérieure. Si vous lancez l’installation sur une version antérieure de Node.js, npm émettra un avertissement EBADENGINE, mais la procédure aboutit généralement : le paquet récupère un binaire précompilé propre à la plateforme et crée un lien symbolique vers celui-ci. Lors de l’exécution, le binaire installé de Claude Code ne tourne toujours pas à l’intérieur de Node.js.

Par conséquent, affirmer que l’exécution de Claude Code nécessite toujours Node.js est techniquement faux. La vérification de la version de Node.js n’est nécessaire que si vous choisissez délibérément l’installation via npm.

Commandes d’installation pour les systèmes pris en charge

Pour garantir une installation correcte, exécutez le script officiel correspondant à votre système d’exploitation et à votre environnement de shell.

macOS, Linux et WSL (Bash / Zsh)

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

Windows PowerShell

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

Invite de commandes Windows (CMD)

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

Installation alternative via npm

npm install -g @anthropic-ai/claude-code

Important : n’exécutez pas cette commande avec sudo npm install -g. L’utilisation des privilèges du superutilisateur entraîne des conflits de permissions de fichiers dans votre répertoire personnel et introduit des risques de sécurité.

Sur la plateforme native Windows, l’installation de Git for Windows est désormais facultative. Si Git for Windows est présent, l’agent peut exécuter des commandes Bash via Git Bash ; s’il n’est pas installé, Claude Code bascule sur son outillage intégré PowerShell.

Vérification de l’installation

Une fois le script d’installation terminé, vérifiez que le binaire est accessible dans votre environnement :

claude --version

L’affichage correct de la version confirme que le binaire a été téléchargé, extrait et enregistré dans votre environnement. Notez qu’un affichage réussi de la version atteste uniquement de l’intégrité du binaire lui-même ; cela ne signifie pas que le client est authentifié ou en mesure d’envoyer des requêtes au modèle.

Pour un audit complet de votre configuration locale, lancez la commande de diagnostic :

claude doctor

La commande claude doctor audite votre environnement local : elle vérifie l’état des fichiers de configuration, les permissions sur le système de fichiers et les dépendances du système, identifiant les problèmes potentiels sans démarrer de session interactive de programmation.

Diagnostic : résoudre les erreurs « command not found »

Si votre terminal indique que la commande claude est introuvable (ou si Windows affiche un message indiquant que la commande n’est pas reconnue en tant que commande interne ou externe), suivez cette procédure de diagnostic :

[Ошибка вызова: claude не найден]
         │
         ▼
[Шаг 1: Открыть новый сеанс терминала]
         │
    Помогло? ──Да──> Завершено
         │ Нет
         ▼
[Шаг 2: Проверить физическое наличие бинарного файла на диске]
         │
    Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку
         │ Да
         ▼
[Шаг 3: Проверить тип установки и PATH]
         │
 ┌───────┴────────────────────────┐
 ▼                                ▼
[Native Install]                [npm Install]
Проверить PATH:                 Проверить PATH через npm prefix -g:
- Unix: ~/.local/bin            - Unix: <prefix>/bin
- Win: %USERPROFILE%\.local\bin - Win: <prefix>
(Не переустанавливать только из-за PATH)

L’arbre de décision ci-dessus détaille la progression du diagnostic :

• Erreur initiale : [Ошибка вызова: claude не найден] correspond à [Erreur d'appel : claude introuvable].
• Étape 1 : [Шаг 1: Открыть новый сеанс терминала] vous invite à ouvrir une nouvelle session de terminal. Si cette action a résolu le problème (Помогло? ──Да──> Завершено / « Est-ce que cela a aidé ? ──Oui──> Terminé »), la procédure est achevée. Si non (Нет / « Non »), passez à l’étape 2.
• Étape 2 : [Шаг 2: Проверить физическое наличие бинарного файла на диске] vérifie la présence physique du fichier binaire sur le disque. S’il est introuvable (Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку / « Fichier trouvé ? ──Non──> Erreur de téléchargement/droits ; répéter l’installation »), relancez le script d’installation. S’il est présent (Да / « Oui »), passez à l’étape 3.
• Étape 3 : [Шаг 3: Проверить тип установки и PATH] analyse votre méthode d’installation et vos variables PATH :
  • Pour Native Install, vérifiez le PATH (Проверить PATH:) : ~/.local/bin sous Unix ou %USERPROFILE%\.local\bin sous Windows.
  • Pour npm Install, vérifiez le PATH via npm prefix -g (Проверить PATH через npm prefix -g:) : <prefix>/bin sous Unix ou <prefix> sous Windows.
  • La remarque située en bas (Не переустанавливать только из-за PATH) met en garde : (Ne pas réinstaller uniquement à cause de problèmes de PATH).

1. Ouvrir une nouvelle session de terminal

Les scripts d’installation modifient les fichiers de configuration de votre shell (.bashrc, .zshrc) ou les variables d’environnement utilisateur de Windows. Les sessions de terminal déjà ouvertes ne prennent pas en compte ces modifications à la volée. Fermez complètement votre fenêtre de terminal actuelle et ouvrez une nouvelle session.

2. Vérifier le chemin physique du binaire

Lors d’une installation Native, l’exécutable est placé dans les répertoires par défaut standards (sauf si ces chemins ont été modifiés par des configurations personnalisées) :

• sur macOS, Linux et WSL : ~/.local/bin/claude (les versions sont conservées dans ~/.local/share/claude) ;
• sur Windows : %USERPROFILE%\.local\bin\claude.exe.

Ces chemins constituent les valeurs par défaut standards, et non des emplacements immuables en présence de substitutions définies par l’utilisateur. Si le fichier est absent du répertoire attendu, le processus d’installation a pu échouer prématurément en raison d’une coupure réseau ou de permissions d’écriture insuffisantes.

3. Exécuter les commandes de diagnostic du shell

Pour déterminer si et comment votre shell localise l’exécutable, utilisez les outils d’inspection natifs :

• sous Zsh / Bash : exécutez command -v claude ou type -a claude ;
• sous PowerShell : lancez Get-Command claude ainsi que where.exe claude ;
• sous CMD : utilisez la commande where claude.

4. Distinguer la résolution du PATH pour Native et pour npm

Une erreur de diagnostic fréquente consiste à tenter d’ajuster les chemins de Node.js lors d’un dysfonctionnement d’une installation Native.

• Si vous avez utilisé Native Install, les répertoires de Node.js et la commande npm prefix -g sont sans rapport avec le problème. Vous devez vérifier et ajouter à la variable PATH le répertoire ~/.local/bin (sur les systèmes Unix) ou %USERPROFILE%\.local\bin (sur Windows).
• Pour une installation via npm install -g, le répertoire des exécutables est défini par la commande npm prefix -g :
  • sur les systèmes de type Unix (macOS, Linux, WSL), l’exécutable est placé dans <prefix>/bin ;
  • sur Windows, l’exécutable se situe directement à la racine de <prefix>. Les commandes npm bin -g et npm root -g n’indiquent pas le chemin correct vers les fichiers exécutables.

Si le binaire est présent sur le disque mais que la commande reste introuvable, inspectez d’abord le PATH et la façon dont le shell résout l’exécutable. Si l’appel du binaire par son chemin absolu complet échoue également, examinez le message d’erreur exact et consultez la documentation officielle de dépannage de l’installation : les permissions d’accès, la compatibilité du binaire avec votre plateforme ou un téléchargement incomplet peuvent être en cause. Ne procédez jamais à une réinstallation à l’aveugle simplement à cause d’une erreur command not found.

Premier lancement et prise en main sécurisée

Une fois la résolution de la commande confirmée, placez-vous dans le répertoire d’un petit projet de test et démarrez une session :

cd /path/to/test-project
claude

Lors du premier lancement, l’interface vous invite à suivre la procédure d’authentification standard via le navigateur. Au sein d’une session active, la commande /status permet de vérifier le répertoire de travail actuel, l’identifiant de compte et le modèle configuré.

Pour une première prise en main, réalisez un exercice d’introduction sans risque avec cette invite :

Объясни назначение основных файлов в проекте. Не изменяй файлы, не устанавливай зависимости и не выполняй команды в терминале.

(Traduction de l’invite de test : « Explique le rôle des principaux fichiers du projet. Ne modifie aucun fichier, n’installe aucune dépendance et n’exécute aucune commande dans le terminal. »)

Résultat attendu précis : l’agent énumère les fichiers principaux et décrit leur rôle sans générer de diff ni modifier le système de fichiers. Une fois la tâche achevée, exécutez la commande git diff dans un autre terminal pour vous assurer que le dépôt est resté strictement intact.

Il est essentiel de comprendre qu’une consigne formulée dans le prompt ne constitue qu’une directive en langage naturel transmise au modèle, et non un mode d’exécution contraignant (enforced mode) ni un bac à sable (sandbox) au niveau du système d’exploitation. Si vous devez restreindre strictement les modifications automatiques de fichiers sur un dépôt, activez le mode plan :

claude --permission-mode plan

En mode plan, l’agent lit les fichiers par défaut et n’utilise les commandes shell qu’en lecture seule, sans modifier le code source. Cependant, ce mode ne constitue pas un bac à sable isolé au niveau de l’OS : lorsque l’exécution automatique est activée, des commandes approuvées par le classificateur peuvent toujours s’exécuter (il ne faut pas présumer d’un cloisonnement strict au niveau du système ; informations confirmées par la documentation au 2026-09-15).

Pour une description détaillée des politiques d’approbation des actions, consultez le guide des autorisations. Pour quitter la session interactive, utilisez le raccourci clavier Ctrl+D.

Connecter un fournisseur d’API indépendant

L’installation de l’utilitaire client et la configuration ultérieure du fournisseur de modèles représentent deux étapes opérationnelles distinctes. Si vous préférez vous connecter via une passerelle tierce compatible Anthropic plutôt que d’utiliser l’authentification par compte standard, les paramètres d’accès se configurent séparément après avoir vérifié le bon fonctionnement local du CLI.

En particulier, le fournisseur d’API indépendant BetterToken met à disposition des développeurs une clé API dédiée, tandis que les statistiques de requêtes vers les modèles, la consommation de tokens et la facturation sont suivies depuis le Dashboard. Les instructions relatives à l’exportation des variables d’environnement et à la définition de l’adresse de base de l’API sont détaillées dans la documentation BetterToken sur Claude Code. Le téléchargement, la mise à jour et l’exécution locale du binaire lui-même s’effectuent toujours au moyen des mécanismes standards du CLI décrits tout au long de ce guide.