Claude Code sur WSL (Windows) : Installation et Optimisation 2026

Claude Code sur WSL : la bonne façon d'utiliser l'agent IA sous Windows

Vous êtes sous Windows et vous voulez utiliser Claude Code, l'agent de codage en ligne de commande d'Anthropic ? La réponse courte des développeurs expérimentés est unanime : passez par WSL2 (Windows Subsystem for Linux). Claude Code est un outil pensé pour un environnement Unix — bash, git, les outils POSIX — et même si une version Windows native existe désormais, c'est sous WSL que l'expérience est la plus stable, la plus rapide et la plus proche de celle des utilisateurs macOS et Linux.

Le problème, c'est que beaucoup de développeurs installent Claude Code "à l'arrache" dans WSL et se retrouvent avec des soucis bien connus : lenteur insupportable, impossible de coller une image, notifications qui ne remontent pas, IDE qui ne se connecte pas. Dans ce guide complet en français, vous allez voir comment installer Claude Code sur WSL proprement, de A à Z, puis comment régler les problèmes de performance et les irritants du quotidien. À la fin, votre terminal Windows sera un vrai poste de développement assisté par IA.

Sommaire

Pourquoi installer Claude Code via WSL plutôt qu'en natif Windows ?<a id="pourquoi-wsl"></a>

Claude Code orchestre en permanence des outils système : il lance des commandes shell, manipule git, exécute vos tests, installe des paquets, parcourt l'arborescence de fichiers. Tout cet écosystème est natif sous Linux et macOS. Sous Windows natif, certains de ces outils se comportent différemment (chemins, permissions, fins de ligne CRLF/LF, scripts .sh), ce qui multiplie les frictions.

WSL2 règle le problème en faisant tourner un vrai noyau Linux à l'intérieur de Windows, avec des performances quasi natives. Concrètement, en travaillant dans WSL, vous obtenez :

Si vous débutez complètement avec l'outil, commencez d'abord par notre guide pour utiliser Claude Code en débutant, puis revenez ici pour le setup Windows. Et pour une vue d'ensemble multi-plateforme, notre tutoriel installer Claude Code sur Mac, Windows et Linux complète bien cette page.

Prérequis : Windows 10/11 et WSL2<a id="prerequis"></a>

Avant de commencer, vérifiez ces quelques points :

Étape 1 : installer WSL2 et Ubuntu<a id="installer-wsl"></a>

Ouvrez PowerShell en tant qu'administrateur et lancez :

wsl --install

Cette commande active les fonctionnalités nécessaires, installe WSL2 et la distribution Ubuntu par défaut. Redémarrez Windows quand on vous le demande. Au redémarrage, une fenêtre Ubuntu s'ouvre et vous demande de créer un nom d'utilisateur Linux et un mot de passe (différents de votre compte Windows).

Vérifiez ensuite que vous êtes bien en version 2 :

wsl --list --verbose

La colonne VERSION doit afficher 2. Si une distribution est en version 1, convertissez-la :

wsl --set-version Ubuntu 2

Mettez aussi à jour le noyau WSL pour éviter bien des bugs :

wsl --update

Étape 2 : installer Node.js dans WSL avec nvm<a id="installer-node"></a>

Claude Code se distribue via npm, il faut donc Node.js. Ne touchez pas au Node installé côté Windows : on installe tout à l'intérieur d'Ubuntu. La meilleure méthode est nvm (Node Version Manager), qui évite les problèmes de permissions.

Dans le terminal Ubuntu (WSL), lancez :

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Fermez puis rouvrez le terminal (ou faites source ~/.bashrc), puis installez la dernière version LTS de Node :

nvm install --lts
node --version
npm --version

Vous devez voir un numéro de version pour Node (idéalement 20.x ou plus récent) et pour npm. Si c'est le cas, vous êtes prêt.

**Astuce** : installer Node via nvm, plutôt que via `apt` ou en global avec `sudo`, vous évite les fameuses erreurs `EACCES` de permissions au moment d'installer un paquet global comme Claude Code.

Étape 3 : installer Claude Code et premier lancement<a id="installer-claude-code"></a>

Toujours dans WSL, installez Claude Code en global :

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

Vérifiez l'installation :

claude --version

Placez-vous ensuite dans le dossier de votre projet stocké dans le système de fichiers Linux (on verra pourquoi c'est crucial juste après), puis lancez l'agent :

cd ~/projets/mon-app
claude

Au premier lancement, Claude Code ouvre un flux de connexion : il vous propose d'ouvrir une page d'authentification dans votre navigateur Windows. Connectez-vous avec votre compte Claude, autorisez, et le terminal récupère la session automatiquement. Aucune clé API à copier-coller.

Avant d'aller plus loin, cette session de Sophiène IA fait le tour complet de Claude Code — installation, fonctionnalités et workflows — et reste la meilleure mise en jambe pour visualiser l'outil en action sous Windows :

Pensez aussi à créer un fichier de configuration projet dès le départ : notre guide complet du fichier CLAUDE.md explique comment donner à l'agent vos conventions, votre architecture et vos commandes — un réflexe qui change tout sous WSL.

Corriger la lenteur de Claude Code sous WSL<a id="lenteur"></a>

C'est LE problème numéro un, et il a une cause unique dans 90 % des cas : vos fichiers sont stockés sur le disque Windows (/mnt/c/...) au lieu du système de fichiers Linux.

WSL2 accède aux fichiers Windows via un pont réseau (9P). Chaque lecture/écriture sur /mnt/c/ est dramatiquement plus lente que sur le disque Linux natif. Or Claude Code lit et parcourt énormément de fichiers (recherche, git status, indexation). Résultat : un agent qui rame.

La règle d'or : stockez vos projets dans le système de fichiers Linux, par exemple sous ~/projets/, jamais sous /mnt/c/Users/....

# LENT (à éviter)
cd /mnt/c/Users/vous/dev/mon-app

# RAPIDE (recommandé)
cd ~/projets/mon-app

Pour migrer un projet existant depuis Windows :

mkdir -p ~/projets
cp -r /mnt/c/Users/vous/dev/mon-app ~/projets/
cd ~/projets/mon-app

Autres optimisations utiles :

[wsl2]
memory=8GB
processors=4
[experimental]
autoMemoryReclaim=gradual

Si malgré tout vos sessions deviennent lourdes à cause du contexte accumulé, jetez un œil à nos conseils pour réduire la facture et gérer les tokens de Claude Code : un contexte plus léger, c'est aussi un agent plus réactif.

Coller une image (paste) dans Claude Code sous WSL<a id="paste-image"></a>

Sous WSL, le Ctrl+V d'une capture d'écran ne fonctionne pas toujours directement, parce que le presse-papiers Windows et l'environnement Linux ne sont pas nativement liés côté image. Trois solutions, de la plus simple à la plus robuste :

Pour les workflows visuels avancés (tests d'interface, captures automatiques), l'intégration d'un serveur de navigation via le protocole MCP est souvent plus puissante qu'un copier-coller manuel.

Activer les notifications WSL<a id="notifications"></a>

Quand Claude Code termine une longue tâche ou attend votre validation, une notification est précieuse. Sous Windows 11, WSL2 prend en charge les notifications natives. Pour que Claude Code vous prévienne, activez les notifications dans sa configuration et assurez-vous que le mode "Concentration" / "Ne pas déranger" de Windows est désactivé.

Vous pouvez aussi brancher une notification système personnalisée via un hook. Si vous voulez automatiser des comportements (notification, formatage, lint) à chaque étape de l'agent, notre guide des hooks Claude Code montre comment déclencher une commande Windows ou Linux à chaque événement.

Connecter VS Code et JetBrains en mode WSL<a id="ide"></a>

L'un des grands intérêts de WSL, c'est de coder dans un IDE Windows tout en exécutant Claude Code dans l'environnement Linux.

VS Code : installez l'extension WSL de Microsoft, puis ouvrez votre projet avec code . depuis le terminal WSL. VS Code bascule en mode "remote WSL". Lancez ensuite claude dans le terminal intégré : la connexion à l'IDE est automatique (diff viewer, partage de sélection).

JetBrains (IntelliJ, PyCharm, WebStorm) : la configuration est un peu plus subtile sous WSL. Nous l'avons détaillée dans notre guide dédié à l'installation de Claude Code dans JetBrains, y compris la fameuse erreur "No available IDEs detected" liée au pare-feu WSL2.

Pour les équipes qui veulent garder la main sur leur infrastructure et auto-héberger leurs agents IA sous Linux, les ressources sur les agents IA open-source et l'auto-hébergement détaillées sur formation-openclaw.com prolongent bien cette logique d'environnement Linux maîtrisé.

Dépannage : les erreurs les plus fréquentes<a id="depannage"></a>

claude: command not found — Le binaire n'est pas dans le PATH. Vérifiez que nvm est bien chargé (source ~/.bashrc) et que l'installation npm s'est faite dans WSL, pas côté Windows.

Erreurs EACCES à l'installation — Vous avez installé Node en global avec sudo. Réinstallez Node via nvm (étape 2) pour des permissions propres.

Authentification qui n'ouvre pas le navigateur — WSL n'arrive pas à lancer votre navigateur Windows. Copiez manuellement l'URL affichée dans le terminal et collez-la dans votre navigateur, puis recollez le code de retour.

Tout est lent — Vos fichiers sont sous /mnt/c/. Déplacez le projet dans ~/ (voir la section lenteur). C'est la cause la plus fréquente.

"No available IDEs detected" — Réseau WSL2 ou pare-feu Windows qui bloque la connexion entre WSL et l'IDE. Passez WSL2 en réseau mirrored (Windows 11) en ajoutant networkingMode=mirrored dans .wslconfig, ou ajoutez une règle de pare-feu autorisant le trafic interne WSL.

Le presse-papiers ou les accents buggent — Mettez à jour Windows Terminal et utilisez-le plutôt que la vieille console cmd.

**Et si vous arrêtiez de vous battre avec votre environnement pour enfin déléguer le code lui-même ?** Une fois Claude Code propre et rapide sous WSL, l'étape suivante n'est pas d'écrire plus de code — c'est d'en écrire moins, en confiant des pans entiers de votre développement à des agents bien configurés. Découvrez comment dans notre programme : [**se faire remplacer par l'IA**](/#inscription). Vous y verrez des workflows complets, du setup jusqu'aux équipes d'agents en production.

FAQ : Claude Code et WSL<a id="faq"></a>

Faut-il vraiment utiliser WSL pour Claude Code sous Windows ?

Une version Windows native de Claude Code existe, mais WSL2 reste recommandé par la plupart des développeurs. L'agent dépend d'outils Unix (bash, git, scripts shell) qui fonctionnent de façon plus fluide et plus prévisible sous Linux. Avec WSL, vous obtenez le même comportement que vos collègues sous macOS et que vos serveurs de production.

Pourquoi Claude Code est-il si lent sous WSL ?

Dans la quasi-totalité des cas, parce que votre projet est stocké sur le disque Windows (/mnt/c/...), auquel WSL2 accède via un pont réseau lent. Déplacez votre projet dans le système de fichiers Linux (~/projets/...) et la vitesse redevient normale. Excluez aussi les dossiers WSL de l'antivirus Windows.

Comment coller une image dans Claude Code sous WSL ?

Le collage direct d'image (Ctrl+V) n'est pas toujours pris en charge sous WSL. La méthode la plus fiable est d'enregistrer l'image dans votre dossier projet Linux, puis de référencer son chemin dans le prompt (ex. Regarde ~/projets/app/capture.png). Windows Terminal et VS Code en mode WSL améliorent aussi le collage d'images.

Quelle distribution Linux choisir pour WSL ?

Ubuntu (installée par défaut par wsl --install) est le choix le plus simple et le mieux documenté pour Claude Code. Debian fonctionne tout aussi bien. L'important est d'être en WSL version 2, pas en version 1, et d'avoir un noyau à jour via wsl --update.

Claude Code installé dans WSL voit-il mes fichiers Windows ?

Oui : depuis WSL, vos disques Windows sont accessibles sous /mnt/c/, /mnt/d/, etc. Mais pour des raisons de performance, ne travaillez pas directement depuis ces chemins. Copiez vos projets dans le système de fichiers Linux et laissez Claude Code y opérer.

Ai-je besoin d'une clé API pour Claude Code sous WSL ?

Non. Claude Code fonctionne avec un abonnement Claude payant (Pro, Max, Team, Enterprise) via une simple connexion au navigateur au premier lancement. Une clé API n'est nécessaire que pour des intégrations via fournisseurs tiers comme Amazon Bedrock ou Google Vertex AI.

Conclusion : un poste de dev Windows enfin à la hauteur

Installer Claude Code sur WSL est, en 2026, la meilleure façon d'utiliser l'agent IA d'Anthropic sous Windows. Le combo est imbattable : un environnement Linux propre, des performances natives, une intégration parfaite avec VS Code et les IDE JetBrains, et zéro friction avec les outils Unix dont l'agent a besoin. Les seuls vrais pièges — la lenteur de /mnt/c/, le paste d'image, les notifications — se règlent en quelques minutes une fois qu'on connaît les bons réflexes.

La prochaine étape consiste à bien configurer l'agent et à automatiser vos workflows pour en tirer le maximum. C'est exactement ce que couvre notre formation. Et pour les équipes qui industrialisent leurs APIs et leurs flux de données autour de ces agents, les ressources sur l'intégration d'APIs et de données côté immoapi.app complètent utilement le sujet MCP.

Pour continuer à maîtriser Claude Code :