Configurar o WSL

Antes de usar o WSL Dashboard, seu Windows deve ter o ambiente WSL 2 corretamente habilitado e configurado. Este documento está dividido nas três partes principais a seguir:

1. Habilitar e configurar o WSL: concluir a instalação e configuração básica do WSL 2.
2. Comando disponível não significa instalação bem-sucedida: explica que o comando wsl poder ser executado não significa que o Linux pode ser instalado com sucesso.
3. Solução de problemas de instalação: métodos de verificação e correção quando a instalação ainda falha após a configuração.

1. Habilitar e configurar o WSL

Este capítulo irá orientá-lo a concluir as configurações básicas necessárias. Após concluir este capítulo, leia o Capítulo 2 para entender a diferença entre comando disponível e instalação bem-sucedida; se ainda houver problemas na instalação, consulte o Capítulo 3.

1.1 Verificar os requisitos do sistema

O WSL 2 tem requisitos mínimos de versão do Windows. Pressione Win + R, digite winver para verificar sua versão:

• Windows 10: versão 1903 ou superior, com build (versão interna) 18362 ou superior.
• Windows 11: todas as versões são suportadas.

IMPORTANT

Se sua versão for muito antiga, primeiro atualize o sistema via "Windows Update".

1.2 Ativar a virtualização de hardware

O WSL 2 é executado com base em tecnologia de virtualização, portanto, você deve habilitar a Virtualization Technology no BIOS/UEFI da placa-mãe.

• Como verificar: abra o "Gerenciador de Tarefas" -> aba "Desempenho" -> "CPU".
• Verificar o status: confirme se o status "Virtualização" no canto inferior direito exibe "Ativada".
• Como ativar: se não estiver ativada, reinicie o computador e entre nas configurações do BIOS/UEFI, encontre uma opção como Intel VT-x ou AMD-V e defina-a como Enabled.

1.3 Habilitar os recursos relacionados do Windows

Você precisa habilitar os recursos "Subsistema do Windows para Linux" e "Plataforma de Máquina Virtual" do Windows.

Método A: pela interface gráfica (recomendado)

1. Pressione Win + S, pesquise e abra "Ativar ou desativar recursos do Windows".
2. Marque os dois itens a seguir:
   • Subsistema do Windows para Linux (Windows Subsystem for Linux)
   • Plataforma de Máquina Virtual (Virtual Machine Platform)
3. Clique em "OK" e reinicie o computador quando solicitado.

Método B: pela linha de comando (privilégios de administrador)

Execute o PowerShell como administrador e execute os seguintes comandos:

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

# Habilitar a plataforma de máquina virtual
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Após a conclusão, reinicie o computador manualmente.

1.4 Instalar/atualizar o kernel do WSL

Versões modernas do Windows podem obter atualizações do WSL pela Microsoft Store.

• Endereço de download: Microsoft Store - Windows Subsystem for Linux
• Download manual: se não for possível usar a Store, baixe o pacote .msixbundle ou .msi mais recente em WSL GitHub Releases para instalação offline.

1.5 Definir o WSL 2 como versão padrão

Para garantir que as novas distribuições instaladas usem o WSL 2 por padrão, execute no terminal:

wsl --set-default-version 2

1.6 Perguntas frequentes

• Erro 0x80370102: geralmente ocorre porque a virtualização não está habilitada no BIOS ou há conflito com o Hyper-V.
• Alternar entre WSL 1 e WSL 2: você pode usar wsl --set-version <nome-da-distribuição> 2 para atualizar uma instância WSL 1 existente para WSL 2.

2. Comando disponível não significa instalação bem-sucedida

O fato de comandos como wsl --version e wsl -l -v serem executados normalmente não significa que as condições para instalar o Linux estão satisfeitas. As duas coisas estão em estágios diferentes e não podem ser equiparadas.

Comando disponível apenas indica:

• ✅ Os componentes WSL do Windows já foram habilitados/instalados
• ✅ A ferramenta de linha de comando wsl.exe está disponível
• ✅ O sistema reconhece os comandos relacionados ao WSL

Mas a instalação bem-sucedida de uma distribuição Linux ainda exige condições adicionais. Os pontos em que normalmente as pessoas ficam presas incluem:

1. Virtualização desativada: VT-x / AMD-V não habilitado no BIOS/UEFI; o WSL 2 não inicia ou reporta erro de virtualização ao instalar a distribuição (veja 1.2 Ativar a virtualização de hardware).
2. Versão/build do Windows muito antigo: o WSL 2 tem requisitos de kernel e versão; versões Home ou imagens empresariais muito antigas podem não ter todos os recursos (veja 1.1 Verificar os requisitos do sistema).
3. Nenhuma distribuição Linux realmente instalada: wsl -l -v apenas lista as distribuições instaladas; quando nada está instalado, a lista fica vazia — isso não significa que o Ubuntu pode ser executado diretamente.
4. Problemas de rede / Microsoft Store: wsl --install -d <distribuição> precisa baixar a imagem da Store ou da rede; redes corporativas, proxies e firewalls podem bloquear.
5. Permissões insuficientes: instalar distribuições ou modificar configurações do WSL exige privilégios de administrador.

TIP

Em resumo: comando WSL funcionando ≠ Linux pronto, você só tem o "ingresso", ainda não instalou o sistema de verdade.

3. Solução de problemas de instalação

Depois de concluir a configuração conforme o Capítulo 1 (ou se você acha que já configurou), se wsl --install ainda falhar, verifique na seguinte ordem.

3.1 Faça primeiro a "verificação em um clique"

Execute o PowerShell como administrador, na ordem:

wsl --install --no-distribution
wsl --set-default-version 2

• ✅ Se ambos os comandos forem executados sem problemas, os componentes opcionais do WSL estão habilitados e as condições de virtualização estão basicamente satisfeitas.
• ❌ Se falhar, será informado diretamente o que está faltando (como Plataforma de Máquina Virtual, Hyper-V, virtualização do BIOS, etc.).

Em seguida, execute systeminfo e confirme se a saída contém Virtualization Enabled In Firmware: Yes. Se não houver erros acima, você pode executar wsl --install para instalar a distribuição com confiança.

NOTE

Nenhum comando pode garantir 100% que wsl --install terá sucesso, mas as verificações acima podem confirmar se as condições de instalação estão satisfeitas.

3.2 Lista de verificação manual

Se a "verificação em um clique" ainda não conseguir localizar o problema, verifique item por item:

1. Verificar se a virtualização do BIOS/firmware está habilitada: execute systeminfo no PowerShell de administrador; a saída deve mostrar Virtualization Enabled In Firmware: Yes.
2. Verificar se os recursos do Windows estão habilitados:

   Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

   O status dos dois comandos deve ser Enabled.
3. Verificar se o WSL está disponível: execute wsl --version e deve haver saída normal; se informar que o comando não existe, significa que o componente WSL não está instalado — volte ao Capítulo 1.
4. Verificar se o WSL 2 pode ser usado (kernel e plataforma de máquina virtual): execute wsl --set-default-version 2 e deve retornar com sucesso. Causas comuns de falha: Plataforma de Máquina Virtual não habilitada, ou VT-x / AMD-V não habilitado no BIOS.

3.3 Consulta rápida de causas comuns de falha

Situação	Descrição	Como resolver
Virtualização não habilitada no BIOS	Falha garantida	Reinicie e entre no BIOS para habilitar VT-x / AMD-V (veja 1.2)
Windows 10 inferior a 19041	wsl --install não suportado	Atualize o sistema (veja 1.1)
Hyper-V/virtualização desabilitada no ambiente corporativo	Pode falhar	Contate o administrador do sistema
Sistema Home Edition antigo	Requer instalação manual	Instale manualmente o kernel do WSL conforme 1.4

3.4 Erro 0xc03a0014: não foi possível encontrar o provedor de suporte a disco virtual

A mensagem de erro é Cannot find a virtual disk support provider for the specified file. Isso não é um problema da própria distribuição Linux, mas sim uma falha na pilha de discos virtuais VHD/VHDX do Windows; o WSL 2 falha ao registrar a distribuição ou ao criar/montar o ext4.vhdx.

Primeiro, faça a verificação mínima: execute o PowerShell como administrador e teste com New-VHD (por exemplo, New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Se esse comando também relatar o mesmo erro, o problema é 100% do lado do Windows, não da distribuição.

Verifique e corrija na seguinte ordem:

1. Serviço Virtual Disk não está em execução: abra services.msc, encontre o serviço Virtual Disk, defina o tipo de inicialização como "Automático" e inicie-o.

2. Recursos WSL / Plataforma de Máquina Virtual não habilitados (ou sem efeito): execute novamente os comandos de 1.3 Habilitar os recursos relacionados do Windows e depois é obrigatório reiniciar. O Windows Home Edition não tem Hyper-V completo, mas o WSL 2 só precisa da Plataforma de Máquina Virtual, não da interface de gerenciamento do Hyper-V.

3. Driver/dispositivo de disco virtual ausente: abra o Gerenciador de Dispositivos e verifique se existem os seguintes itens em "Dispositivos do sistema / Controladores de armazenamento":

   • Microsoft Virtual Disk Provider
   • Microsoft Virtual Drive Enumerator
   • Microsoft VHD Loopback Controller

   Se estiverem ausentes, você pode adicioná-los manualmente via hdwwiz.exe (Controladores de armazenamento → Microsoft → Microsoft VHD Loopback Controller) e confirmar que o serviço FsDepends não está desabilitado.

4. A imagem importada não atende aos requisitos do WSL: ao usar wsl --import --vhd, o VHDX deve ser do sistema de arquivos ext4; não pode ser disco criptografado com LUKS, raw.img comum, ISO Live ou disco vazio formatado com NTFS/FAT. Arquivos .img / .qcow2 / .iso não podem ser importados diretamente com wsl --import --vhd.

5. Problemas de caminho/permissão/sistema de arquivos: o diretório de destino deve estar em um disco NTFS (FAT32/exFAT não funcionam); evite caracteres chineses, espaços e símbolos especiais no caminho; não importe de unidades de rede, OneDrive ou pastas compactadas; use um PowerShell de administrador real (não um terminal comum).

6. Componentes do sistema corrompidos: execute o DISM e o SFC em sequência para reparar os componentes do sistema e tente novamente:

   DISM.exe /Online /Cleanup-Image /RestoreHealth
   sfc /scannow

TIP

Máquinas virtuais de terceiros (VirtualBox, VMware) ou recursos de sandbox/endurecimento de softwares de segurança (como 360, Huorong) podem interferir nas operações de disco virtual; durante a solução de problemas, você pode desativá-los temporariamente.