WSL2: O Guia Completo de Linux no Windows para Desenvolvedores

O Windows Subsystem for Linux 2 (WSL2) mudou fundamentalmente a forma como os desenvolvedores trabalham no Windows. Em vez de fazer dual boot, executar maquinas virtuais pesadas ou lutar com camadas de compatibilidade, agora voce pode executar um ambiente Linux completo nativamente ao lado do Windows com desempenho quase nativo. Seja escrevendo Node.js, Python, Go, Rust ou qualquer outra linguagem, o WSL2 oferece ferramentas Linux genuinas sem sair da sua area de trabalho Windows.

Este guia leva voce por tudo o que precisa para configurar um ambiente de desenvolvimento Linux de nivel profissional no Windows usando WSL2. Abordaremos a instalacao, configuracao do Ubuntu, configuracao do Windows Terminal, integracao com Docker, desenvolvimento remoto com VS Code, melhores praticas do sistema de arquivos, rede, suporte GPU e gerenciamento de multiplas distribuicoes.

Pre-requisitos

Antes de comecar, certifique-se de ter:

• Windows 10 versao 2004 (build 19041) ou posterior, ou Windows 11
• Pelo menos 8 GB de RAM (16 GB recomendados para cargas de trabalho com Docker)
• Virtualizacao habilitada na sua BIOS/UEFI (Intel VT-x ou AMD-V)
• Uma conexao com a internet para baixar distribuicoes
• PowerShell ou Windows Terminal com privilegios de Administrador

Nota: Se voce esta executando o Windows 10, certifique-se de que todas as atualizacoes do Windows estejam instaladas. Builds mais antigos podem ter suporte parcial ao WSL2 com bugs conhecidos. O Windows 11 fornece a melhor experiencia com WSL2, incluindo suporte a systemd e renderizacao nativa de aplicacoes GUI do Linux.

O Que E o WSL2?

WSL2 (Windows Subsystem for Linux versao 2) e uma camada de compatibilidade integrada ao Windows que permite executar executaveis binarios do Linux nativamente. Ao contrario do WSL1, que traduzia chamadas de sistema Linux em chamadas ao kernel do Windows NT, o WSL2 executa um kernel Linux real dentro de uma maquina virtual leve Hyper-V.

Caracteristicas principais do WSL2:

• Kernel Linux real: O WSL2 inclui um kernel Linux mantido pela Microsoft (baseado no kernel 5.15+ a partir de 2025) que recebe atualizacoes regulares atraves do Windows Update.
• Compatibilidade total com chamadas de sistema: Por executar um kernel genuino, o WSL2 suporta ferramentas como Docker, systemd, sistemas de arquivos FUSE e eBPF que o WSL1 nao conseguia lidar.
• Leve: A maquina virtual inicia em aproximadamente um segundo e consome recursos minimos quando ociosa.
• Integracao estreita com Windows: Voce pode chamar executaveis do Windows a partir do Linux, acessar arquivos do Windows a partir do Linux (e vice-versa), e usar rede localhost entre os dois sistemas.

# Check your current WSL version
wsl --version

WSL1 vs WSL2

Entender as diferencas ajuda voce a escolher a versao correta para seu fluxo de trabalho:

Recurso	WSL1	WSL2
Arquitetura	Camada de traducao	VM leve com kernel real
Kernel Linux	Nenhum (traducao de syscalls)	Kernel Linux completo
Desempenho do sistema de arquivos (arquivos Linux)	Moderado	Velocidade nativa ext4
Desempenho do sistema de arquivos (arquivos Windows)	Rapido (acesso NTFS direto)	Mais lento (protocolo 9P)
Compatibilidade com chamadas de sistema	Parcial (~70%)	Completa (100%)
Suporte Docker	Nao	Sim
Suporte systemd	Nao	Sim (Windows 11)
Uso de memoria	Menor	Dinamico (cresce/diminui)
Tempo de inicializacao	Instantaneo	~1 segundo
Rede	Compartilha a pilha de rede do Windows	Adaptador ethernet virtual

Para a maioria dos desenvolvedores, WSL2 e a escolha correta. O unico cenario onde o WSL1 pode ser preferivel e quando voce precisa acessar intensivamente arquivos armazenados na particao NTFS do Windows, ja que o WSL1 tem acesso mais rapido a arquivos entre sistemas operacionais.

Instalando o WSL2 e o Ubuntu

A Microsoft simplificou significativamente o processo de instalacao. Em builds modernos do Windows, um unico comando lida com tudo:

Instalacao simplificada (recomendada)

Abra o PowerShell como Administrador e execute:

wsl --install

Este comando habilita os recursos do Windows necessarios (Plataforma de Maquina Virtual e Subsistema Windows para Linux), baixa o kernel Linux WSL2 mais recente, define o WSL2 como padrao e instala o Ubuntu.

Reinicie seu computador quando solicitado:

# After restart, Ubuntu will launch automatically for first-time setup
# You will be prompted to create a UNIX username and password

Instalacao manual (builds mais antigos do Windows)

Se wsl --install nao estiver disponivel, habilite os recursos manualmente:

# Enable WSL feature
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Restart your computer, then set WSL2 as default
wsl --set-default-version 2

Instalar uma distribuicao especifica

Voce pode escolher entre varias distribuicoes:

# List all available distributions
wsl --list --online

# Install a specific distribution
wsl --install -d Ubuntu-24.04

# Other popular options:
# wsl --install -d Debian
# wsl --install -d openSUSE-Tumbleweed
# wsl --install -d kali-linux

Configuracao Inicial do Ubuntu

Apos sua distribuicao Ubuntu ser executada pela primeira vez e voce criar sua conta de usuario, execute estes passos essenciais de configuracao:

Atualizar o sistema

sudo apt update && sudo apt upgrade -y

Instalar ferramentas essenciais de desenvolvimento

sudo apt install -y build-essential git curl wget unzip zip \
  software-properties-common apt-transport-https \
  ca-certificates gnupg lsb-release

Configurar o Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input

Importante: Definir core.autocrlf como input garante que o Git converta finais de linha estilo Windows (CRLF) para estilo Unix (LF) ao fazer commit, mas deixe os finais LF intactos ao fazer checkout. Isso previne problemas de finais de linha ao compartilhar codigo entre ferramentas Windows e Linux.

Gerar chaves SSH

ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Display the public key to add to GitHub/GitLab
cat ~/.ssh/id_ed25519.pub

Configurar um prompt de shell melhorado (opcional)

Muitos desenvolvedores preferem Zsh com Oh My Zsh para uma experiencia de terminal mais produtiva:

sudo apt install -y zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Configuracao do Windows Terminal

O Windows Terminal e o aplicativo de terminal recomendado para WSL2. Ele suporta multiplas abas, paineis divididos, renderizacao de texto acelerada por GPU e personalizacao profunda.

Instalacao

Instale o Windows Terminal pela Microsoft Store ou via winget:

winget install --id Microsoft.WindowsTerminal -e

Configurar o Ubuntu como perfil padrao

Abra as configuracoes do Windows Terminal (Ctrl+,) e defina seu perfil Ubuntu como padrao. No arquivo settings.json, voce tambem pode personalizar a aparencia:

{
  "defaultProfile": "{YOUR-UBUNTU-GUID}",
  "profiles": {
    "list": [
      {
        "name": "Ubuntu",
        "source": "Windows.Terminal.Wsl",
        "startingDirectory": "//wsl$/Ubuntu/home/yourusername",
        "fontFace": "CascadiaCode NF",
        "fontSize": 11,
        "colorScheme": "One Half Dark",
        "cursorShape": "filledBox"
      }
    ]
  }
}

Atalhos de teclado uteis

Atalho	Acao
Ctrl+Shift+T	Nova aba
Ctrl+Shift+D	Duplicar painel
Alt+Shift+D	Dividir painel
Ctrl+Tab	Alternar abas
Ctrl+Shift+W	Fechar painel

Melhores Praticas do Sistema de Arquivos

Entender o desempenho do sistema de arquivos no WSL2 e critico para um fluxo de trabalho produtivo. Esta e uma das fontes mais comuns de confusao e frustracao para novos usuarios do WSL2.

A regra de ouro

Armazene os arquivos do seu projeto dentro do sistema de arquivos Linux, nao na unidade do Windows.

# FAST: Files in your Linux home directory
# Path: ~/projects/my-app
# Actual location: ext4 file system inside WSL2 VM
cd ~/projects/my-app
time git status  # ~0.1 seconds

# SLOW: Files on the Windows drive accessed from WSL2
# Path: /mnt/c/Users/yourname/projects/my-app
# Crosses the 9P protocol bridge on every file operation
cd /mnt/c/Users/yourname/projects/my-app
time git status  # ~2-5 seconds (10-50x slower)

Por que a diferenca de desempenho existe

O WSL2 executa dentro de uma VM leve com seu proprio sistema de arquivos ext4. Acessar arquivos na particao NTFS do Windows requer cruzar o limite da VM usando o protocolo 9P, o que adiciona latencia a cada operacao de arquivo. Para uma pasta node_modules com milhares de arquivos pequenos, essa sobrecarga se torna dramatica.

Acessar arquivos entre os dois sistemas

Embora voce deva armazenar projetos no lado Linux, voce ainda pode acessar arquivos de ambos os sistemas:

# From WSL2, access Windows files
ls /mnt/c/Users/yourname/Documents

# From Windows Explorer, access Linux files
# Type this in the Explorer address bar:
# \\wsl$\Ubuntu\home\yourusername\projects

# From PowerShell, access Linux files
explorer.exe \\wsl$\Ubuntu\home\yourusername

Estrutura de diretorios recomendada

mkdir -p ~/projects ~/tools ~/scripts
# Keep all development work under ~/projects
# Keep downloaded tools under ~/tools
# Keep automation scripts under ~/scripts

Integracao do Docker Desktop com WSL2

O Docker Desktop para Windows usa o WSL2 como seu backend, fornecendo desempenho nativo de conteineres Linux sem a sobrecarga de uma VM Hyper-V tradicional.

Instalacao

1. Baixe e instale o Docker Desktop para Windows.
2. Durante a instalacao, certifique-se de que “Use WSL 2 instead of Hyper-V” esteja selecionado.
3. Apos a instalacao, abra as configuracoes do Docker Desktop e navegue ate Resources > WSL Integration.
4. Habilite a integracao com sua distribuicao Ubuntu.

Verificar a instalacao

Do seu terminal Ubuntu no WSL2:

docker --version
docker compose version
docker run hello-world

Gerenciamento de recursos

O Docker Desktop com WSL2 pode consumir memoria significativa. Configure limites em ~/.wslconfig no lado Windows:

# Create/edit C:\Users\yourname\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=2GB

Apos modificar .wslconfig, reinicie o WSL2:

wsl --shutdown

Executar conteineres

Como o Docker executa dentro da VM do WSL2, voce obtem desempenho completo de conteineres Linux:

# Run an Nginx container
docker run -d -p 8080:80 --name webserver nginx

# Access it from both WSL2 and Windows browser at http://localhost:8080

# Run a development database
docker run -d -p 5432:5432 \
  -e POSTGRES_PASSWORD=devpassword \
  --name devdb postgres:16

# Use Docker Compose for multi-container setups
docker compose up -d

Para um guia completo de instalacao do Docker no Ubuntu, consulte nosso artigo sobre Como Instalar Docker no Ubuntu.

Extensao VS Code Remote - WSL

A extensao Remote - WSL do Visual Studio Code permite usar o VS Code no Windows enquanto executa todas as ferramentas, terminais e extensoes dentro do WSL2. Esta e a forma recomendada de editar codigo armazenado no sistema de arquivos Linux.

Configuracao

1. Instale o Visual Studio Code no Windows (nao dentro do WSL2).
2. Instale a extensao WSL (identificador: ms-vscode-remote.remote-wsl).
3. Abra um terminal WSL2 e navegue ate o diretorio do seu projeto.
4. Inicie o VS Code a partir do terminal:

cd ~/projects/my-app
code .

O VS Code instalara seu componente servidor dentro do WSL2 automaticamente e se conectara a ele. Voce vera “WSL: Ubuntu” no canto inferior esquerdo do VS Code, confirmando que esta executando no modo remoto.

Beneficios principais

• Extensoes executam dentro do WSL2: Servidores de linguagem, linters, depuradores e formatadores executam no ambiente Linux, eliminando problemas de compatibilidade entre sistemas operacionais.
• O terminal e um shell Linux real: O terminal integrado e seu bash/zsh do WSL2, nao o PowerShell.
• A observacao de arquivos funciona nativamente: O hot-reload para frameworks como React, Vue e Next.js funciona sem configuracao adicional porque o observador de arquivos opera no sistema de arquivos Linux.
• A integracao Git usa o Git do Linux: O VS Code usa o binario Git dentro do WSL2, evitando problemas de finais de linha e caminhos.

Extensoes recomendadas para desenvolvimento no WSL2

Instale estas extensoes dentro do ambiente WSL2 (elas aparecerao sob “WSL: Ubuntu - Installed”):

# From inside WSL2 terminal
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension ms-python.python
code --install-extension golang.go
code --install-extension bradlc.vscode-tailwindcss

Rede Entre Windows e WSL2

A rede do WSL2 evoluiu significativamente. Em builds modernos do Windows 11 com WSL2 2.0+, a rede usa o modo espelhado por padrao, o que simplifica a maioria dos cenarios de conectividade.

Acessar servicos do WSL2 a partir do Windows

Por padrao, servicos executando dentro do WSL2 sao acessiveis a partir do Windows via localhost:

# Start a development server in WSL2
python3 -m http.server 3000

# Access it from Windows browser: http://localhost:3000

Acessar servicos do Windows a partir do WSL2

Voce pode alcancar servicos do Windows a partir do WSL2 usando localhost tambem (modo espelhado no Windows 11), ou usar o IP do host Windows:

# Find the Windows host IP (useful for older builds)
cat /etc/resolv.conf | grep nameserver
# Output example: nameserver 172.28.80.1

# Or use the hostname
ping "$(hostname).local"

Configurar rede em modo espelhado (Windows 11)

Adicione ao seu arquivo .wslconfig no Windows:

# C:\Users\yourname\.wslconfig
[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true

Redirecionamento de portas para acesso externo

Se voce precisa que dispositivos externos acessem servicos executando no WSL2:

# Forward port 3000 from Windows to WSL2 (run as Administrator)
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=localhost

# Remove the forwarding rule when no longer needed
netsh interface portproxy delete v4tov4 listenport=3000 listenaddress=0.0.0.0

# List all forwarding rules
netsh interface portproxy show v4tov4

Suporte a GPU e CUDA

O WSL2 suporta passthrough de GPU, permitindo executar cargas de trabalho CUDA, frameworks de aprendizado de maquina e ate aplicacoes graficas do Linux diretamente.

Pre-requisitos

• Uma GPU NVIDIA com um driver recente do Windows (Game Ready ou Studio driver 470.76+)
• Windows 11 ou Windows 10 build 21H2+

Verificar acesso a GPU

# Check if the GPU is visible
nvidia-smi

# You should see your GPU model, driver version, and CUDA version

Instalar o CUDA Toolkit dentro do WSL2

# Do NOT install a Linux NVIDIA driver inside WSL2 -- use the Windows driver
# Only install the CUDA toolkit

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install -y cuda-toolkit

Testar com PyTorch

pip install torch torchvision
python3 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'Device: {torch.cuda.get_device_name(0)}')"

Importante: Nunca instale um driver de video NVIDIA do Linux dentro do WSL2. O driver GPU do Windows lida com o passthrough da GPU. Instalar um driver Linux causara conflitos.

Gerenciando Multiplas Distribuicoes

O WSL2 permite executar multiplas distribuicoes Linux simultaneamente, o que e util para testar em diferentes ambientes ou isolar cargas de trabalho.

Instalar distribuicoes adicionais

# List available distributions
wsl --list --online

# Install additional distributions
wsl --install -d Debian
wsl --install -d Ubuntu-22.04

Alternar entre distribuicoes

# List installed distributions and their status
wsl --list --verbose

# Launch a specific distribution
wsl -d Debian

# Set a default distribution
wsl --set-default Ubuntu-24.04

Exportar e importar distribuicoes

Isso e util para criar backups ou compartilhar ambientes pre-configurados com sua equipe:

# Export a distribution to a tar file
wsl --export Ubuntu-24.04 D:\backups\ubuntu-24.04-backup.tar

# Import a distribution from a tar file
wsl --import MyCustomUbuntu D:\wsl\MyCustomUbuntu D:\backups\ubuntu-24.04-backup.tar

# Launch the imported distribution
wsl -d MyCustomUbuntu

Remover uma distribuicao

# Unregister and delete a distribution (WARNING: destroys all data)
wsl --unregister Debian

Referencia de Comandos WSL

Aqui esta uma tabela de referencia completa dos comandos WSL mais importantes:

Comando	Descricao
wsl --install	Instalar WSL com a distribuicao Ubuntu padrao
wsl --install -d <distro>	Instalar uma distribuicao especifica
wsl --list --online	Listar todas as distribuicoes disponiveis
wsl --list --verbose	Listar distribuicoes instaladas com versao e estado
wsl --set-default-version 2	Definir WSL2 como padrao para novas instalacoes
wsl --set-default <distro>	Definir a distribuicao padrao
wsl --set-version <distro> 2	Converter uma distribuicao WSL1 para WSL2
wsl --shutdown	Desligar todas as distribuicoes em execucao e a VM
wsl --terminate <distro>	Encerrar uma distribuicao especifica
wsl --export <distro> <file>	Exportar uma distribuicao para um arquivo tar
wsl --import <name> <path> <file>	Importar uma distribuicao de um arquivo tar
wsl --unregister <distro>	Remover uma distribuicao e deletar todos seus dados
wsl --update	Atualizar o kernel Linux do WSL2
wsl --version	Exibir versao do WSL, versao do kernel e versao do WSLg
wsl --status	Mostrar configuracao do WSL e distribuicao padrao
wsl -d <distro> -u root	Iniciar uma distribuicao como usuario root
wsl hostname -I	Exibir o endereco IP da VM do WSL2

Solucao de Problemas

O WSL2 nao inicia com um erro de virtualizacao

Se voce ver um erro como “Please enable the Virtual Machine Platform Windows feature”, verifique se a virtualizacao esta habilitada na sua BIOS/UEFI:

# Check if virtualization is enabled
systeminfo | findstr /i "Hyper-V"

# Re-enable the required features
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all

O WSL2 usa muita memoria

Por padrao, o WSL2 pode consumir ate 50% da sua memoria total do sistema. Crie ou edite C:\Users\yourname\.wslconfig:

[wsl2]
memory=4GB
swap=2GB

Depois reinicie o WSL2:

wsl --shutdown

A resolucao DNS falha dentro do WSL2

Se ping google.com falha mas ping 8.8.8.8 funciona, o DNS e o problema:

# Temporary fix: manually set DNS
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo bash -c 'echo "nameserver 8.8.4.4" >> /etc/resolv.conf'

# Prevent WSL from overwriting resolv.conf
sudo bash -c 'echo "[network]" > /etc/wsl.conf'
sudo bash -c 'echo "generateResolvConf = false" >> /etc/wsl.conf'

Depois reinicie o WSL2 com wsl --shutdown no PowerShell.

Desvio do relogio entre Windows e WSL2

Apos um ciclo de suspensao/hibernacao do Windows, o relogio do WSL2 pode desviar:

# Check the clock
date

# Sync the clock manually
sudo hwclock -s

# Or on newer builds
sudo ntpdate time.windows.com

Permissoes de arquivo estao incorretas em unidades montadas do Windows

# Add to /etc/wsl.conf inside your distribution
[automount]
enabled = true
options = "metadata,umask=22,fmask=11"
mountFsTab = false

Erro “Cannot connect to Docker daemon”

# Verify Docker Desktop is running on Windows
# Then check the WSL2 integration setting in Docker Desktop:
# Settings > Resources > WSL Integration > Enable for your distro

# Restart WSL2
wsl --shutdown

# Verify Docker works
docker ps

Resumo

O WSL2 transforma o Windows em uma plataforma de desenvolvimento de primeira classe para fluxos de trabalho baseados em Linux. Com um kernel Linux real, desempenho nativo do sistema de arquivos, integracao com Docker e conectividade perfeita com o VS Code, voce pode aproveitar o melhor de ambos os sistemas operacionais sem compromissos.

Para aproveitar ao maximo seu ambiente WSL2:

1. Sempre armazene os arquivos do projeto no sistema de arquivos Linux para desempenho otimo.
2. Use o Windows Terminal com perfis personalizados para cada distribuicao.
3. Aproveite o VS Code Remote - WSL para manter sua experiencia de edicao no Windows enquanto executa tudo no Linux.
4. Configure .wslconfig para gerenciar a alocacao de memoria e processadores para suas cargas de trabalho.
5. Use o Docker Desktop com o backend WSL2 para cargas de trabalho com conteineres — consulte nosso guia completo de instalacao do Docker para mais detalhes.
6. Automatize seus fluxos de trabalho com pipelines CI/CD assim que seu ambiente de desenvolvimento estiver pronto. Confira nosso guia sobre Primeiros Passos com GitHub Actions para CI/CD para levar seus projetos ao proximo nivel.

Com o WSL2 configurado corretamente, voce tem um ambiente de desenvolvimento Linux poderoso, flexivel e de alto desempenho executando diretamente na sua maquina Windows.