Introdução aos contêineres remotos do Docker no WSL 2

2025-06-10

Este guia passo a passo ajudará você a começar a desenvolver com contêineres remotos configurando o Docker Desktop para Windows com o WSL 2 (Subsistema do Windows para Linux, versão 2).

O Docker Desktop para Windows fornece um ambiente de desenvolvimento para criar, enviar e executar aplicativos dockerizados. Ao habilitar o mecanismo baseado em WSL 2, você pode executar contêineres do Linux e do Windows no Docker Desktop no mesmo computador. (O Docker Desktop é gratuito para uso pessoal e pequenas empresas, para obter informações sobre preços pro, equipe ou negócios, consulte as perguntas frequentes do site do Docker).

Observação

É recomendável usar o Docker Desktop devido à integração com o Windows e o Subsistema do Windows para Linux. No entanto, enquanto o Docker Desktop dá suporte à execução de contêineres do Linux e do Windows, você não pode executar ambos simultaneamente. Para executar contêineres do Linux e do Windows simultaneamente, você precisaria instalar e executar uma instância separada do Docker no WSL. Se você precisar executar contêineres simultâneos ou simplesmente preferir instalar um mecanismo de contêiner diretamente na distribuição do Linux, siga as instruções de instalação do Linux para esse serviço de contêiner, como Instalar o Mecanismo do Docker no Ubuntu ou Instalar o Podman para executar contêineres do Linux.

Visão geral dos contêineres do Docker

O Docker é uma ferramenta usada para criar, implantar e executar aplicativos usando contêineres. Os contêineres permitem que os desenvolvedores empacotem um aplicativo com todas as partes necessárias (bibliotecas, estruturas, dependências etc. ) e enviem tudo como um pacote. O uso de um contêiner garante que o aplicativo seja executado da mesma forma, independentemente de qualquer configuração personalizada ou bibliotecas instaladas anteriormente no computador que o executa, que podem ser diferentes do computador usado para gravar e testar o código do aplicativo. Isso permite que os desenvolvedores se concentrem em escrever código sem se preocupar com o sistema em que o código será executado.

Os contêineres do Docker são semelhantes às máquinas virtuais, mas não criam um sistema operacional virtual inteiro. Em vez disso, o Docker permite que o aplicativo use o mesmo kernel do Linux que o sistema em que ele está sendo executado. Isso permite que o pacote do aplicativo exija apenas partes que ainda não estão no computador host, reduzindo o tamanho do pacote e melhorando o desempenho.

A disponibilidade contínua, usando contêineres do Docker com ferramentas como o Kubernetes, é outro motivo para a popularidade dos contêineres. Isso permite que várias versões do contêiner do aplicativo sejam criadas em momentos diferentes. Em vez de precisar derrubar um sistema inteiro para atualizações ou manutenção, cada contêiner (e seus microsserviços específicos) pode ser substituído em tempo real. Você pode preparar um novo contêiner com todas as suas atualizações, configurar o contêiner para produção e apenas apontar para o novo contêiner quando ele estiver pronto. Você também pode arquivar diferentes versões do seu aplicativo usando contêineres e mantê-las em execução como um fallback de segurança, se necessário.

Para saber mais, confira Introdução aos contêineres do Docker.

Pré-requisitos

WSL versão 1.1.3.0 ou posterior.
Windows 11 64 bits: Home ou Pro versão 21H2 ou superior, ou Enterprise ou Education versão 21H2 ou superior.
Windows 10 de 64 bits (recomendado): Home ou Pro 22H2 (build 19045) ou superior, ou Enterprise ou Education 22H2 (build 19045) ou superior. (Mínimo): Home ou Pro 21H2 (build 19044) ou superior, ou Enterprise ou Education 21H2 (build 19044) ou superior. Atualizar o Windows
Processador de 64 bits com SLAT (Tradução de Endereço de Segundo Nível).
RAM do sistema de 4 GB.
Habilitar a virtualização de hardware no BIOS.
Instale o WSL e configure um nome de usuário e uma senha para sua distribuição do Linux em execução no WSL 2.
Instale o Visual Studio Code(opcional). Isso fornecerá a melhor experiência, incluindo a capacidade de codificar e depurar dentro de um contêiner remoto do Docker e conectado à distribuição do Linux.
Instalar o Terminal do Windows(opcional). Isso fornecerá a melhor experiência, incluindo a capacidade de personalizar e abrir vários terminais na mesma interface (incluindo Ubuntu, Debian, PowerShell, CLI do Azure ou o que preferir usar).
Inscreva-se para uma ID do Docker no Hub do Docker(opcional).
Consulte o contrato de licença do Docker Desktop para obter atualizações sobre os termos de uso.

Para obter mais informações, consulte os requisitos do Sistema de documentos do Docker para instalar o Docker Desktop no Windows.

Para saber como instalar o Docker no Windows Server, confira Introdução: Preparar o Windows para contêineres.

Observação

O WSL pode executar distribuições no modo WSL versão 1 ou WSL 2. Você pode verificar isso abrindo o PowerShell e inserindo: wsl -l -v. Verifique se a distribuição está definida para usar o WSL 2 inserindo: wsl --set-version <distro> 2. Substitua <distro> pelo nome da distribuição (por exemplo, Ubuntu 18.04).

No WSL versão 1, devido a diferenças fundamentais entre o Windows e o Linux, o Mecanismo do Docker não pôde ser executado diretamente dentro do WSL, portanto, a equipe do Docker desenvolveu uma solução alternativa usando Hyper-V VMs e LinuxKit. No entanto, como o WSL 2 agora é executado em um kernel do Linux com capacidade total de chamada do sistema, o Docker pode ser totalmente executado no WSL 2. Isso significa que os contêineres do Linux podem ser executados nativamente sem emulação, resultando em melhor desempenho e interoperabilidade entre suas ferramentas Windows e Linux.

Instalar o Docker Desktop

Com o back-end do WSL 2 com suporte no Docker Desktop para Windows, você pode trabalhar em um ambiente de desenvolvimento baseado em Linux e criar contêineres baseados em Linux, usando o Visual Studio Code para edição e depuração de código e executando seu contêiner no navegador Microsoft Edge no Windows.

Para instalar o Docker (depois de já instalar o WSL):

Baixe o Docker Desktop e siga as instruções de instalação.
Depois de instalado, inicie o Docker Desktop no menu Iniciar do Windows e selecione o ícone do Docker no menu ícones ocultos da barra de tarefas. Clique com o botão direito do mouse no ícone para exibir o menu de comandos do Docker e selecione "Configurações".
Verifique se "Usar o mecanismo baseado em WSL 2" está marcado em Configurações>Gerais.
Selecione entre as distribuições do WSL 2 instaladas para as quais você deseja habilitar a integração do Docker indo em: Configurações>Recursos>Integração WSL.
Para confirmar se o Docker foi instalado, abra uma distribuição WSL (por exemplo, Ubuntu) e exiba a versão e o número de build inserindo: docker --version
Teste se a instalação funciona corretamente executando uma imagem simples interna do Docker usando: docker run hello-world

Dica

Aqui estão alguns comandos úteis do Docker para saber:

Liste os comandos disponíveis na CLI do Docker inserindo: docker
Listar informações para um comando específico com: docker <COMMAND> --help
Liste as imagens do Docker na sua máquina (que é apenas a imagem hello-world neste momento), com: docker image ls --all
Liste os contêineres em seu computador com: docker container ls --all ou docker ps -a (sem a flag -a para exibir todos, somente os contêineres em execução serão exibidos)
Liste informações de todo o sistema sobre a instalação do Docker, incluindo estatísticas e recursos (CPU &memória) disponíveis para você no contexto do WSL 2, com: docker info

Desenvolver em contêineres remotos usando o VS Code

Para começar a desenvolver aplicativos usando o Docker com o WSL 2, recomendamos usar o VS Code, juntamente com as extensões WSL, Contêineres de Desenvolvimento e Docker.

Instale a extensão WSL do VS Code. Essa extensão permite que você abra seu projeto do Linux em execução no WSL no VS Code (não é necessário se preocupar com problemas de caminho, compatibilidade binária ou outros desafios entre sistemas operacionais).
Instale a extensão contêineres de desenvolvimento do VS Code. Essa extensão permite que você abra sua pasta de projeto ou repositório dentro de um contêiner, aproveitando o conjunto completo de recursos do Visual Studio Code para fazer seu trabalho de desenvolvimento dentro do contêiner.
Instale a extensão do Docker do VS Code. Essa extensão adiciona a funcionalidade para criar, gerenciar e implantar aplicativos em contêineres de dentro do VS Code. (Você precisa da extensão Contêineres de Desenvolvimento para realmente usar o contêiner como seu ambiente de desenvolvimento.)

Vamos usar o Docker para criar um contêiner de desenvolvimento para um projeto de aplicativo existente.

Para este exemplo, usarei o código-fonte do meu tutorial Olá, Mundo para Django nos documentos de configuração do ambiente de desenvolvimento do Python. Você pode pular esta etapa se preferir usar seu próprio código-fonte do projeto. Para baixar meu aplicativo Web HelloWorld-Django do GitHub, abra um terminal WSL (Ubuntu, por exemplo) e insira: git clone https://github.com/mattwojo/helloworld-django.git

Observação

Sempre armazene seu código no mesmo sistema de arquivos no qual você está usando ferramentas. Isso resultará em um desempenho mais rápido de acesso a arquivos. Neste exemplo, estamos usando uma distribuição do Linux (Ubuntu) e queremos armazenar nossos arquivos de projeto no sistema \\wsl\de arquivos WSL. Armazenar arquivos de projeto no sistema de arquivos do Windows diminuiria significativamente a velocidade ao usar ferramentas do Linux no WSL para acessar esses arquivos.
No terminal do WSL, altere os diretórios para a pasta de código-fonte deste projeto:
```
cd helloworld-django
```
Abra o projeto no VS Code em execução no servidor de extensão WSL local inserindo:
```
code .
```
Confirme se você está conectado à distribuição do WSL Linux verificando o indicador remoto verde no canto inferior esquerdo da instância do VS Code.
Na paleta de comandos do VS Code (Ctrl + Shift + P), digite: Dev Containers: Reabrir no Contêiner, pois estamos usando uma pasta que já foi aberta com a extensão WSL. Como alternativa, use Contêineres de Desenvolvimento: Abrir Pasta no Contêiner... para escolher uma pasta WSL usando o compartilhamento local \\wsl$ (do lado do Windows). Confira o início rápido do Visual Studio Code : abra uma pasta existente em um contêiner para obter mais detalhes. Se esses comandos não forem exibidos quando você começar a digitar, verifique se você instalou a extensão Contêineres de Desenvolvimento vinculada acima.
Selecione a pasta do projeto que você deseja colocar em contêiner. No meu caso, isso é \\wsl\Ubuntu-20.04\home\mattwojo\repos\helloworld-django\
Uma lista de definições de contêiner será exibida, pois ainda não há nenhuma configuração de contêiner de desenvolvimento na pasta do projeto (repositório). A lista de definições de configuração de contêiner que aparece é filtrada com base no tipo de projeto. Para meu projeto do Django, selecionarei Python 3.
Uma nova instância do VS Code será aberta, começará a compilar nossa nova imagem e, depois que o build for concluído, iniciará nosso contêiner. Você verá que uma nova pasta .devcontainer apareceu com informações de configuração do contêiner dentro de um arquivo Dockerfile e de um arquivo devcontainer.json.
Para confirmar se o projeto ainda está conectado ao WSL e em um contêiner, abra o terminal integrado do VS Code (Ctrl + Shift + ~). Verifique o sistema operacional inserindo: uname e a versão do Python com: python3 --version. Você pode ver que o uname voltou como "Linux", portanto, você ainda está conectado ao mecanismo WSL 2 e o número de versão do Python será baseado na configuração do contêiner que pode ser diferente da versão do Python instalada na distribuição do WSL.
Para executar e depurar seu aplicativo dentro do contêiner usando o Visual Studio Code, primeiro abra o menu Executar (Ctrl+Shift+D ou selecione a guia na barra de menus à esquerda). Em seguida, selecione Executar e Depurar para selecionar uma configuração de depuração e escolha a configuração mais adequada ao seu projeto (no meu exemplo, este será "Django"). Isso criará um launch.json arquivo na .vscode pasta do projeto com instruções sobre como executar seu aplicativo.
De dentro do VS Code, selecione Executar>Iniciar depuração (ou basta pressionar a tecla F5 ). Isso abrirá um terminal dentro do VS Code e você verá um resultado dizendo algo como: "Iniciando o servidor de desenvolvimento em http://127.0.0.1:8000/ Encerrar o servidor com CONTROL-C". Mantenha pressionada a tecla Control e selecione o endereço exibido para abrir seu aplicativo no navegador da Web padrão e veja seu projeto em execução dentro de seu contêiner.

Agora você configurou com êxito um contêiner de desenvolvimento remoto usando o Docker Desktop, alimentado pelo back-end do WSL 2, que você pode codificar, compilar, executar, implantar ou depurar usando o VS Code!

Resolução de problemas

Contexto do Docker do WSL descontinuado

Se você estava utilizando uma Prévia Técnica inicial do Docker para WSL, você pode ter um contexto do Docker chamado "wsl" que agora está obsoleto e não é mais utilizado. Você pode verificar com o comando: docker context ls. Você pode remover esse contexto "wsl" para evitar erros com o comando: docker context rm wsl como você deseja usar o contexto padrão para Windows e WSL2.

Os possíveis erros que você pode encontrar com esse contexto wsl preterido incluem: 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.

Para obter mais informações sobre esse problema, consulte Como configurar o Docker no Windows System para Linux (WSL2) no Windows 10.

Problema ao localizar a pasta de armazenamento de imagens do Docker

O Docker cria duas pastas de distribuição para armazenar dados:

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

Você pode encontrar essas pastas abrindo sua distribuição do WSL Linux e inserindo: explorer.exe . para exibir a pasta no Explorador de Arquivos do Windows. Insira: \\wsl\<distro name>\mnt\wsl substituindo <distro name> pelo nome da sua distribuição (ou seja, Ubuntu-20.04) para ver essas pastas.

Saiba mais sobre como localizar locais de armazenamento do Docker no WSL, consulte esse problema no repositório WSL ou nesta postagem stackOverflow.

Para obter mais ajuda com problemas gerais de solução de problemas no WSL, consulte o documento de solução de problemas .

Compartilhar via