Vous installez un package Python, pip retourne une erreur liée à une dépendance compilée, et la solution trouvée sur GitHub suppose que vous êtes sous Linux. Ou bien vos scripts tournent parfaitement en local, puis se comportent différemment sur le serveur de production — qui, lui, tourne sous Ubuntu. Ces deux situations ont la même cause : Python et une grande partie de son écosystème ont été conçus avec Linux comme environnement de référence. Windows ajoute une couche de friction que les workarounds contournent rarement proprement.
WSL2 règle ce problème à la racine. En faisant tourner un vrai noyau Linux à l’intérieur de Windows, il rend votre poste local structurellement identique à un serveur Linux. VS Code, que 75,9 % des développeurs utilisent selon le Stack Overflow Developer Survey 2025 (plus de 49 000 répondants), dispose d’une extension officielle pour piloter cet environnement directement depuis son interface. Ce qui suit couvre l’enchaînement complet : WSL2 activé, Python installé côté Linux, VS Code branché sur cet environnement.
Pourquoi WSL2 change réellement quelque chose pour Python
Le problème avec Python sous Windows n’est pas Python lui-même, c’est l’écart entre les hypothèses de l’écosystème et la plateforme. Beaucoup de bibliothèques supposent qu’elles tournent sur Linux — au niveau des appels système, des chemins, des dépendances natives compilées. Quand cette hypothèse est fausse, les erreurs surviennent à l’installation ou, pire, à l’exécution.
WSL1 apportait une couche de traduction des appels système Linux vers Windows. Utile, mais limité : certains syscalls n’étaient pas supportés, et les performances sur les I/O fichiers pouvaient être dégradées. WSL2 change d’architecture : il embarque un vrai noyau Linux, ce qui supprime la couche de traduction pour les workloads qui en ont besoin. La compatibilité syscall est complète, et les performances dans le système de fichiers Linux natif sont nettement meilleures qu’en WSL1.
Pour Python, la conséquence est concrète : l’environnement de développement et l’environnement de production partagent le même noyau Linux. Ce qui fonctionne dans WSL2 fonctionne sur le serveur.
Prérequis avant de commencer
- Version de Windows requise : WSL2 nécessite Windows 10 build 19041 ou supérieur, ou Windows 11. Pour vérifier votre build, tapez
winverdans la barre de recherche Windows. En dessous de ce seuil, le protocole décrit ici ne s’applique pas. - Windows S Mode ou environnement d’entreprise : L’activation de WSL peut être bloquée par une politique système. Si vous êtes sur un poste géré par une DSI, vérifiez les restrictions avant de continuer.
- Projets dépendant d’API Windows natives : WSL ne donne pas accès aux API Windows (COM, pilotes matériels, SDK Windows natifs). Si votre projet Python en dépend, cette approche ne lui convient pas.
Activer WSL2 et installer Ubuntu
Ouvrez PowerShell en tant qu’administrateur, puis exécutez :
wsl --installCette commande active la fonctionnalité WSL, installe le noyau Linux WSL2 et télécharge Ubuntu par défaut. Un redémarrage est demandé. Au redémarrage, Ubuntu se lance pour sa première configuration : choisissez un nom d’utilisateur Linux et un mot de passe (distincts de vos identifiants Windows).
Si vous souhaitez une distribution différente, la commande wsl --list --online liste les options disponibles, et wsl --install -d NomDistribution installe celle de votre choix. Les commandes d’installation de Python varient ensuite selon le gestionnaire de paquets : apt pour Ubuntu et Debian, dnf pour Fedora. Les étapes suivantes utilisent apt.
Pour confirmer que WSL2 est actif (et non WSL1), exécutez dans PowerShell :
wsl --list --verboseLa colonne VERSION doit afficher 2 pour votre distribution.
Installer Python dans WSL, pas dans Windows
Ouvrez un terminal Ubuntu (depuis le menu Démarrer ou via la commande wsl dans PowerShell), puis mettez à jour les paquets et installez Python :
sudo apt update && sudo apt upgrade -y
sudo apt install python3 python3-pip python3-venv -yVérifiez ensuite que l’interpréteur actif est bien celui de Linux :
which python3Le chemin retourné doit commencer par /usr/bin/ ou /usr/local/bin/, pas par /mnt/c/. Un chemin commençant par /mnt/c/ signifie que le shell appelle l’interpréteur Windows monté dans WSL — ce qui annule le bénéfice de toute la démarche.
Un point sur les fichiers de projet : stockez-les dans votre répertoire Linux (/home/votre-utilisateur/) plutôt que dans /mnt/c/. L’accès depuis WSL au système de fichiers Windows via /mnt/c/ est possible, mais les performances I/O sont significativement moins bonnes que dans le système de fichiers Linux natif — ce qui se ressent sur les projets avec beaucoup de fichiers.
Connecter VS Code à WSL et ouvrir un projet Linux
Installez l’extension dédiée depuis le marketplace VS Code. Selon la version de VS Code que vous avez, elle s’appelle WSL, Remote – WSL, ou fait partie du pack Remote Development. Dans tous les cas, cherchez « WSL » dans le marketplace et installez l’extension publiée par Microsoft.
Une fois installée, deux façons de connecter VS Code à WSL :
- Depuis le terminal Ubuntu, naviguez vers votre dossier de projet et tapez
code .. VS Code s’ouvre en mode distant, connecté à WSL. - Depuis VS Code, utilisez la palette de commandes (Ctrl+Shift+P) et cherchez « WSL: Connect to WSL ». Une fois connecté, ouvrez un dossier situé dans
/home/votre-utilisateur/.
L’indicateur de connexion dans le coin inférieur gauche de VS Code doit afficher quelque chose comme WSL: Ubuntu. Si cet indicateur reste vide ou affiche « Local », VS Code travaille encore dans Windows.
Vérifiez ensuite le terminal intégré : ouvrez-le avec Ctrl+` et confirmez que le shell est bien Bash (ou le shell de votre distribution Linux), pas PowerShell ni cmd. Si ce n’est pas le cas, passez par les paramètres VS Code pour définir le terminal par défaut en mode WSL. Ce point passe souvent inaperçu mais invalide silencieusement le setup : les commandes pip install et python tapées dans un terminal PowerShell dans VS Code n’affectent pas l’environnement Linux.
Créer un environnement virtuel et le sélectionner dans VS Code
Depuis le terminal Linux de VS Code (vérifié à l’étape précédente), dans le répertoire de votre projet :
python3 -m venv .venv
source .venv/bin/activatePour sélectionner cet interpréteur dans VS Code, ouvrez la palette de commandes (Ctrl+Shift+P) et cherchez « Python: Select Interpreter ». VS Code liste les interpréteurs détectés. Choisissez celui dont le chemin pointe vers .venv/bin/python dans votre projet Linux. Si le venv n’apparaît pas immédiatement, utilisez l’option « Entrer le chemin de l’interpréteur » et saisissez le chemin manuellement.
Une fois sélectionné, la barre d’état de VS Code affiche le chemin de l’interpréteur actif. Confirmez qu’il contient .venv et un chemin Linux, pas Windows.
Checklist de validation du setup
- ☐ WSL2 actif :
wsl --list --verboseaffiche VERSION 2 pour la distribution cible - ☐ Distribution installée et configurée : un utilisateur Linux créé, terminal Ubuntu fonctionnel
- ☐ Python dans WSL :
which python3retourne un chemin commençant par/usr/ou/usr/local/ - ☐ Fichiers de projet dans le système de fichiers Linux : chemin du projet sous
/home/, pas sous/mnt/c/ - ☐ VS Code connecté à WSL : indicateur WSL visible dans le coin inférieur gauche
- ☐ Terminal intégré VS Code = shell Linux : Bash ou zsh, pas PowerShell ni cmd
- ☐ Venv créé et sélectionné : la barre d’état VS Code affiche un chemin interpréteur contenant
.venvet un chemin Linux
Quand ces sept points sont verts, votre environnement est fonctionnel. Les packages installés via le terminal VS Code s’installent dans Linux, l’interpréteur que VS Code utilise pour l’analyse statique et l’exécution est celui du venv Linux, et l’écart avec un serveur de production Ubuntu est réduit à presque rien.
WSL2 reste inadapté si votre projet doit appeler des API Windows natives — pour ces cas, une machine virtuelle Windows complète reste l’alternative la plus directe. Pour tout le reste, le setup décrit ici supprime la principale source de divergence entre un poste Windows et un serveur Linux en production.