Commencez avec les conteneurs distants Docker sur WSL 2

2025-06-10

Ce guide pas à pas vous aidera à commencer à développer avec des conteneurs distants en configurant Docker Desktop pour Windows avec WSL 2 (sous-système Windows pour Linux, version 2).

Docker Desktop pour Windows fournit un environnement de développement pour la création, l’expédition et l’exécution d’applications dockerized. En activant le moteur WSL 2, vous pouvez exécuter à la fois des conteneurs Linux et Windows dans Docker Desktop sur le même ordinateur. (Docker Desktop est gratuit pour une utilisation personnelle et les petites entreprises, pour plus d’informations sur les tarifs Pro, Équipe ou Entreprise, consultez les FAQ sur le site Docker).

Remarque

Nous vous recommandons d’utiliser Docker Desktop en raison de son intégration à Windows et au sous-système Windows pour Linux. Toutefois, alors que Docker Desktop prend en charge l’exécution des conteneurs Linux et Windows, vous ne pouvez pas exécuter les deux simultanément. Pour exécuter simultanément des conteneurs Linux et Windows, vous devez installer et exécuter une instance Docker distincte dans WSL. Si vous devez exécuter des conteneurs simultanés ou préférez simplement installer un moteur de conteneur directement dans votre distribution Linux, suivez les instructions d’installation Linux pour ce service de conteneur, telles que Installer le moteur Docker sur Ubuntu ou installer Podman pour exécuter des conteneurs Linux.

Vue d’ensemble des conteneurs Docker

Docker est un outil utilisé pour créer, déployer et exécuter des applications à l’aide de conteneurs. Les conteneurs permettent aux développeurs de empaqueter une application avec toutes les parties dont elle a besoin (bibliothèques, frameworks, dépendances, etc.) et de les expédier en tant que package unique. L’utilisation d’un conteneur garantit que l’application s’exécute de la même façon, quels que soient les paramètres personnalisés ou les bibliothèques précédemment installées sur l’ordinateur exécutant celui-ci pouvant différer de l’ordinateur utilisé pour écrire et tester le code de l’application. Cela permet aux développeurs de se concentrer sur l’écriture de code sans vous soucier du système sur lequel le code sera exécuté.

Les conteneurs Docker sont similaires aux machines virtuelles, mais ne créent pas un système d’exploitation virtuel entier. Au lieu de cela, Docker permet à l’application d’utiliser le même noyau Linux que le système sur lequel elle s’exécute. Cela permet au package d’application de ne nécessiter que des parties non déjà sur l’ordinateur hôte, ce qui réduit la taille du package et améliore les performances.

La disponibilité continue, à l’aide de conteneurs Docker avec des outils comme Kubernetes, est une autre raison de la popularité des conteneurs. Cela permet à plusieurs versions de votre conteneur d’application d’être créées à différents moments. Au lieu de devoir retirer un système entier pour les mises à jour ou la maintenance, chaque conteneur (et ses microservices spécifiques) peut être remplacé à la volée. Vous pouvez préparer un nouveau conteneur avec toutes vos mises à jour, configurer le conteneur pour la production et pointer simplement vers le nouveau conteneur une fois qu’il est prêt. Vous pouvez également archiver différentes versions de votre application à l’aide de conteneurs et les maintenir en cours d’exécution en tant que secours de sécurité si nécessaire.

Pour en savoir plus, consultez Présentation des conteneurs Docker.

Conditions préalables

WSL version 1.1.3.0 ou ultérieure.
Windows 11 64 bits : Famille ou Professionnel version 21H2 ou ultérieure, Entreprise ou Éducation version 21H2 ou ultérieure.
Windows 10 64 bits (recommandé) : Famille ou Professionnel 22H2 (build 19045) ou version ultérieure, Ou Entreprise ou Éducation 22H2 (build 19045) ou version ultérieure. (Minimum) : Accueil ou Pro 21H2 (build 19044) ou supérieur, ou Entreprise ou Éducation 21H2 (build 19044) ou supérieur. Mettre à jour Windows
Processeur 64 bits avec traduction d’adresses de deuxième niveau (SLAT).
RAM système de 4 Go.
Activer la virtualisation matérielle dans le BIOS.
Installez WSL et configurez un nom d’utilisateur et un mot de passe pour votre distribution Linux s’exécutant dans WSL 2.
Installez Visual Studio Code(facultatif). Cela offre la meilleure expérience, notamment la possibilité de coder et de déboguer à l’intérieur d’un conteneur Docker distant et connectée à votre distribution Linux.
Installez Windows Terminal(facultatif). Cela offre la meilleure expérience, notamment la possibilité de personnaliser et d’ouvrir plusieurs terminaux dans la même interface (y compris Ubuntu, Debian, PowerShell, Azure CLI ou tout ce que vous préférez utiliser).
Inscrivez-vous à un ID Docker sur Docker Hub(facultatif).
Consultez le contrat de licence Docker Desktop pour connaître les mises à jour des conditions d’utilisation.

Pour plus d’informations, consultez la configuration système requise pour docker docs pour installer Docker Desktop sur Windows.

Pour savoir comment installer Docker sur Windows Server, consultez Prise en main : Préparation de Windows pour conteneurs.

Remarque

WSL peut exécuter des distributions en mode WSL version 1 ou WSL 2. Vous pouvez vérifier cela en ouvrant PowerShell et en entrant : wsl -l -v. Vérifiez que votre distribution est configurée pour utiliser WSL 2 en entrant : wsl --set-version <distro> 2. Remplacez <distro> par le nom de distribution (par exemple, Ubuntu 18.04).

Dans WSL version 1, en raison de différences fondamentales entre Windows et Linux, le moteur Docker n’a pas pu s’exécuter directement dans WSL. L’équipe Docker a donc développé une solution alternative à l’aide de machines virtuelles Hyper-V et linuxKit. Toutefois, étant donné que WSL 2 s’exécute désormais sur un noyau Linux avec une capacité d’appel système complète, Docker peut s’exécuter entièrement dans WSL 2. Cela signifie que les conteneurs Linux peuvent s’exécuter en mode natif sans émulation, ce qui améliore les performances et l’interopérabilité entre vos outils Windows et Linux.

Installer Docker Desktop

Avec le back-end WSL 2 pris en charge dans Docker Desktop pour Windows, vous pouvez travailler dans un environnement de développement Linux et créer des conteneurs Linux, tout en utilisant Visual Studio Code pour la modification et le débogage du code, et exécuter votre conteneur dans le navigateur Microsoft Edge sur Windows.

Pour installer Docker (après avoir déjà installé WSL) :

Téléchargez Docker Desktop et suivez les instructions d’installation.
Une fois installé, démarrez Docker Desktop à partir du menu Démarrer de Windows, puis sélectionnez l’icône Docker dans le menu icônes masquées de votre barre des tâches. Cliquez avec le bouton droit sur l’icône pour afficher le menu Commandes Docker, puis sélectionnez « Paramètres ».
Vérifiez que « Utiliser le moteur basé sur WSL 2 » est coché dans Paramètres>Généraux.
Sélectionnez parmi vos distributions WSL 2 installées celles sur lesquelles vous souhaitez activer l’intégration Docker en allant dans : Paramètres>Ressources>Intégration WSL.
Pour vérifier que Docker a été installé, ouvrez une distribution WSL (par exemple Ubuntu) et affichez la version et le numéro de build en entrant : docker --version
Testez que votre installation fonctionne correctement en exécutant une image Docker intégrée simple à l’aide de : docker run hello-world

Conseil / Astuce

Voici quelques commandes Docker utiles à connaître :

Répertoriez les commandes disponibles dans l’interface CLI Docker en entrant : docker
Répertorier les informations d’une commande spécifique avec : docker <COMMAND> --help
Répertoriez les images Docker sur votre machine (qui est simplement l’image hello-world à ce stade) avec : docker image ls --all
Répertoriez les conteneurs sur votre ordinateur, avec : docker container ls --all ou docker ps -a (sans le -a afficher tous les indicateurs, seuls les conteneurs en cours d’exécution seront affichés)
Répertoriez les informations à l’échelle du système concernant l’installation de Docker, notamment les statistiques et les ressources (processeur et mémoire) disponibles dans le contexte WSL 2, avec : docker info

Développer dans des conteneurs distants à l’aide de VS Code

Pour commencer à développer des applications à l’aide de Docker avec WSL 2, nous vous recommandons d’utiliser VS Code, ainsi que les extensions WSL, Dev Containers et Docker.

Installez l’extension WSL VS Code. Cette extension vous permet d’ouvrir votre projet Linux s’exécutant sur WSL dans VS Code (il n’est pas nécessaire de vous soucier des problèmes de chemin d’accès, de compatibilité binaire ou d’autres défis inter-systèmes d’exploitation).
Installez l’extension Vs Code Dev Containers. Cette extension vous permet d’ouvrir votre dossier de projet ou votre dépôt à l’intérieur d’un conteneur, en tirant parti de l’ensemble de fonctionnalités complètes de Visual Studio Code pour effectuer votre travail de développement dans le conteneur.
Installez l’extension Docker VS Code. Cette extension ajoute la fonctionnalité de génération, de gestion et de déploiement d’applications conteneurisées à partir de VS Code. (Vous avez besoin de l’extension Dev Containers pour utiliser réellement le conteneur comme environnement de développement.)

Utilisons Docker pour créer un conteneur de développement pour un projet d’application existant.

Pour cet exemple, j’utiliserai le code source de mon didacticiel Hello World pour Django dans l’environnement de développement Python configuré dans la documentation. Vous pouvez ignorer cette étape si vous préférez utiliser votre propre code source de projet. Pour télécharger mon application web HelloWorld-Django à partir de GitHub, ouvrez un terminal WSL (Ubuntu par exemple) et entrez : git clone https://github.com/mattwojo/helloworld-django.git

Remarque

Stockez toujours votre code dans le même système de fichiers que celui dans lequel vous utilisez des outils. Cela entraîne des performances d’accès aux fichiers plus rapides. Dans cet exemple, nous utilisons une distribution Linux (Ubuntu) et souhaitons stocker nos fichiers projet sur le système \\wsl\de fichiers WSL. Le stockage des fichiers projet sur le système de fichiers Windows ralentit considérablement les choses lors de l’utilisation d’outils Linux dans WSL pour accéder à ces fichiers.
À partir de votre terminal WSL, remplacez les répertoires par le dossier de code source de ce projet :
```
cd helloworld-django
```
Ouvrez le projet dans VS Code s’exécutant sur le serveur d’extension WSL local en entrant :
```
code .
```
Vérifiez que vous êtes connecté à votre distribution Linux WSL en vérifiant l’indicateur distant vert dans le coin inférieur gauche de votre instance VS Code.
Dans la palette de commandes de VS Code (Ctrl + Maj + P), entrez : Dev Containers : Rouvrez dans le conteneur, car nous utilisons déjà un dossier ouvert avec l’extension WSL. Vous pouvez également utiliser Dev Containers : Ouvrir le dossier dans conteneur... pour choisir un dossier WSL à l’aide du partage local \\wsl$ (côté Windows). Pour plus d’informations, consultez le démarrage rapide de Visual Studio Code : Ouvrez un dossier existant dans un conteneur . Si ces commandes ne s’affichent pas lorsque vous commencez à taper, vérifiez que vous avez installé l’extension Dev Containers liée ci-dessus.
Sélectionnez le dossier de projet que vous souhaitez conteneuriser. Dans mon cas, c’est \\wsl\Ubuntu-20.04\home\mattwojo\repos\helloworld-django\
Une liste de définitions de conteneur s’affiche, car il n’existe pas encore de configuration de conteneur de développement dans le dossier de projet (référentiel). La liste des définitions de configuration de conteneur qui s’affiche est filtrée en fonction du type de projet. Pour mon projet Django, je sélectionne Python 3.
Une nouvelle instance de VS Code s’ouvre, commence à générer notre nouvelle image et une fois la build terminée, démarre notre conteneur. Vous verrez qu'un nouveau dossier .devcontainer est apparu avec des informations de configuration de conteneur à l'intérieur d'un fichier Dockerfile et d'un fichier devcontainer.json.
Pour vérifier que votre projet est toujours connecté à WSL et au sein d’un conteneur, ouvrez le terminal intégré VS Code (Ctrl+ Maj + ~). Vérifiez le système d’exploitation en entrant : uname et la version python avec : python3 --version. Vous pouvez voir que le nom uname est revenu sous la forme « Linux », vous êtes donc toujours connecté au moteur WSL 2, et le numéro de version Python sera basé sur la configuration du conteneur qui peut différer de la version python installée sur votre distribution WSL.
Pour exécuter et déboguer votre application à l’intérieur du conteneur à l’aide de Visual Studio Code, ouvrez d’abord le menu Exécuter (Ctrl+Maj+D ou sélectionnez l’onglet dans la barre de menus de gauche). Sélectionnez Ensuite Exécuter et Déboguer pour sélectionner une configuration de débogage et choisissez la configuration qui convient le mieux à votre projet (dans mon exemple, il s’agit de « Django »). Cela crée un launch.json fichier dans le dossier de votre projet avec des instructions sur l’exécution .vscode de votre application.
Dans VS Code, sélectionnez Démarrer>le débogage (ou appuyez simplement sur la touche F5 ). Cela ouvre un terminal à l’intérieur de VS Code et vous devriez voir un résultat indiquant quelque chose comme : « Démarrage du serveur de développement au moment de http://127.0.0.1:8000/ quitter le serveur avec CONTROL-C ». Maintenez la touche Contrôle enfoncée et sélectionnez l’adresse affichée pour ouvrir votre application dans votre navigateur web par défaut et voyez votre projet s’exécuter à l’intérieur de son conteneur.

Vous avez maintenant configuré un conteneur de développement distant à l’aide de Docker Desktop, alimenté par le serveur principal WSL 2, que vous pouvez coder dans, générer, exécuter, déployer ou déboguer à l’aide de VS Code !

Résolution des problèmes

Contexte Docker WSL dépassé et obsolète

Si vous utilisiez un aperçu technique précoce de Docker pour WSL, vous pouvez avoir un contexte Docker appelé « wsl » qui est désormais déconseillé et n’est plus utilisé. Vous pouvez vérifier avec la commande : docker context ls. Vous pouvez supprimer ce contexte « wsl » pour éviter les erreurs avec la commande : docker context rm wsl comme vous souhaitez utiliser le contexte par défaut pour Windows et WSL2.

Les erreurs possibles que vous pouvez rencontrer avec ce contexte wsl déconseillé sont les suivantes : docker wsl open //./pipe/docker_wsl: The system cannot find the file specified. ou error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.

Pour plus d’informations sur ce problème, consultez Comment configurer Docker dans Le système Windows pour Linux (WSL2) sur Windows 10.

Problèmes de recherche du dossier de stockage d’images Docker

Docker crée deux dossiers de distribution pour stocker des données :

\wsl$\docker-desktop
\wsl$\docker-desktop-data

Vous trouverez ces dossiers en ouvrant votre distribution Linux WSL et en entrant : explorer.exe . pour afficher le dossier dans l’Explorateur de fichiers Windows. Entrez : \\wsl\<distro name>\mnt\wsl remplacez <distro name> par le nom de votre distribution (par exemple : Ubuntu-20.04) pour voir ces dossiers.

Pour plus d’informations sur la localisation des emplacements de stockage Docker dans WSL, consultez ce problème à partir du dépôt WSL ou de ce billet StackOverflow.

Pour obtenir de l’aide sur les problèmes généraux de résolution des problèmes dans WSL, consultez le document de résolution des problèmes .

Partager via