Habilitar e configurar o WSL

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

1. Habilitar e configurar o WSL: concluir a instalação e a configuração básica do WSL 2.
2. Comando disponível não significa instalação bem-sucedida: explica que o comando wsl executável 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 reparo quando a instalação ainda falha após a configuração.

1. Habilitar e configurar o WSL

Este capítulo vai 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 a instalação ainda apresentar problemas, 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, e o número de build deve ser 18362 ou superior.
• Windows 11: todas as versões são compatíveis.

IMPORTANT

Se sua versão for muito antiga, primeiro atualize seu sistema através do "Windows Update".

1.2 Habilitar a virtualização de hardware

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

• Método de verificação: abra o "Gerenciador de Tarefas" -> guia "Desempenho" -> "CPU".
• Verificar o status: confirme que o status "Virtualização" no canto inferior direito mostra "Habilitado".
• Forma de habilitar: se não estiver habilitada, você precisa reiniciar o computador, acessar as configurações do BIOS/UEFI, encontrar uma opção similar a Intel VT-x ou AMD-V e defini-la como Enabled.

1.3 Habilitar os recursos relacionados do Windows

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

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

1. Pressione Win + S, procure 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 (com 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 execução, reinicie manualmente o computador.

1.4 Instalar ou atualizar o kernel do WSL

As versões modernas do Windows podem obter as atualizações do WSL através da Microsoft Store.

• URL de download: Microsoft Store - Windows Subsystem for Linux
• Download manual: se não puder usar a loja, você pode baixar o pacote de instalação .msixbundle ou .msi mais recente do 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 Problemas comuns

• Erro 0x80370102: geralmente causado pela virtualização não habilitada no BIOS ou por conflitos com o Hyper-V.
• Alternância 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 o WSL 2.

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

Comandos como wsl --version, wsl -l -v podem ser executados normalmente, mas isso não significa que as condições para instalar o Linux já estão satisfeitas. As duas coisas estão em fases diferentes e não devem ser equiparadas.

Um comando disponível indica apenas que:

• ✅ o componente WSL está habilitado/instalado no Windows
• ✅ a ferramenta de linha de comando wsl.exe está disponível
• ✅ o sistema reconhece os comandos relacionados ao WSL

Mas instalar com sucesso uma distribuição Linux ainda exige condições adicionais. Os pontos de travamento comuns são:

1. Virtualização desativada: VT-x / AMD-V não está habilitado no BIOS/UEFI, o WSL 2 não consegue iniciar ou é relatado um erro de virtualização ao instalar a distribuição (método de verificação: ver 1.2 Habilitar a virtualização de hardware).
2. Versão/build do Windows muito antiga: o WSL 2 tem requisitos de kernel e versão; a edição Home ou imagens corporativas muito antigas podem ter recursos incompletos (método de verificação: ver 1.1 Verificar os requisitos do sistema).
3. Nenhuma distribuição Linux realmente instalada: wsl -l -v lista apenas as distribuições instaladas; se nada estiver instalado, a lista fica vazia, o que não significa que você possa executar o Ubuntu diretamente.
4. Problemas de rede / Microsoft Store: wsl --install -d <distribuição> precisa baixar a imagem da loja ou da rede; a rede da empresa, proxies e firewalls podem bloquear o processo.
5. Permissões insuficientes: instalar uma distribuição ou modificar as configurações do WSL exige privilégios de administrador.

TIP

Em resumo: um comando WSL disponível não significa Linux pronto; você só obteve um "ingresso de entrada", mas ainda não instalou o sistema de verdade.

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

Após concluir a configuração conforme o capítulo 1 (ou se você achar que já concluiu), se wsl --install ainda falhar, verifique na seguinte ordem.

3.1 Fazer primeiro a verificação de um clique

Execute em sequência, com privilégios de administrador, no PowerShell:

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

• ✅ Se os dois comandos forem executados sem problemas, significa que os componentes opcionais do WSL estão habilitados e as condições de virtualização estão basicamente satisfeitas.
• ❌ Se falhar, será indicado diretamente o que falta (por exemplo, plataforma de máquina virtual, Hyper-V, virtualização do BIOS etc.).

Depois execute systeminfo e confirme que Virtualization Enabled In Firmware: Yes aparece na saída. Se nenhuma das verificações acima apresentar erros, em geral você pode executar wsl --install com segurança para instalar uma distribuição.

NOTE

Nenhum comando pode garantir 100 % de sucesso do wsl --install, mas as verificações acima confirmam se as condições de instalação estão satisfeitas.

3.2 Lista de verificação manual

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

1. Verificar se a virtualização do BIOS/firmware está habilitada: no PowerShell como administrador, execute systeminfo; 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: wsl --version deve produzir uma saída normal; se for indicado que o comando não existe, o componente WSL não está instalado; volte ao capítulo 1.
4. Verificar se o WSL 2 está disponível (kernel e plataforma de máquina virtual): wsl --set-default-version 2 deve retornar com sucesso. Causas comuns de falha: a plataforma de máquina virtual não está habilitada ou o VT-x / AMD-V não está habilitado no BIOS.

3.3 Referência rápida das causas de falha comuns

Situação	Explicação	Forma de tratamento
Virtualização não habilitada no BIOS	Falha garantida	Reiniciar e habilitar VT-x / AMD-V no BIOS (ver 1.2)
Windows 10 inferior a 19041	Não suporta wsl --install	Atualizar o sistema (ver 1.1)
Hyper-V / virtualização desabilitada no ambiente corporativo	Pode falhar	Entrar em contato com o administrador do sistema
Edição Home antiga	Requer instalação manual	Instalar manualmente o kernel do WSL conforme 1.4

3.4 Erro 0xc03a0014: provedor de suporte de disco virtual não encontrado

A mensagem de erro é Cannot find a virtual disk support provider for the specified file. Não é um problema da distribuição Linux em si, mas da pilha de discos virtuais VHD/VHDX do Windows que não está funcionando corretamente: o WSL 2 falha ao registrar a distribuição e ao criar/montar o ext4.vhdx.

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

Verifique e repare na seguinte ordem:

1. O 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 do 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 é necessário reiniciar. A edição Home do Windows 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. Drivers/dispositivos de disco virtual ausentes: 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 com o hdwwiz.exe (Controladores de armazenamento → Microsoft → Microsoft VHD Loopback Controller) e confirme 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 um sistema de arquivos ext4; não pode ser um disco criptografado com LUKS, uma raw.img comum, uma ISO live ou um disco vazio formatado em NTFS/FAT. Arquivos .img / .qcow2 / .iso não podem ser usados diretamente com wsl --import --vhd.

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

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

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

TIP

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