Em 2010, publiquei um livro sobre fazer Windows e Linux se comunicarem um com o outro pela rede. Naquela época, compartilhar uma pasta entre os dois era um projeto de fim de semana com um arquivo de configuração e muita paciência. Dezesseis anos depois, o Windows envia Linux dentro de si mesmo e você o instala com um comando. Nunca foi tão fácil usar o terminal no Windows, até mesmo executando alguns aplicativos Linux dentro dele.
Então aqui está a resposta para quem está configurando Claude Code no Windows em 2026: WSL não é mais obrigatório. Claude Code é executado nativamente no Windows 10 versão 1809 e posterior. Instale-o dentro do WSL 2 quando seu projeto depender de ferramentas Linux, ou quando você quiser execução de comandos em sandbox, que de acordo com a documentação de configuração da Anthropic funciona em WSL 2 e em nenhum outro lugar no Windows.
A maioria dos guias de WSL ainda em circulação foi escrita quando essa escolha não existia. Alguns deles afirmam explicitamente que a Anthropic não envia nenhuma compilação Windows nativa. Isso não é mais verdade.
Este é um acompanhamento do post Claude Code macOS setup, e a maioria dessa configuração se mantém inalterada.
O que WSL realmente é
WSL 2 é um kernel Linux real em execução em uma máquina virtual leve que a Microsoft envia com Windows. Seu sistema de arquivos Linux fica dentro de um disco rígido virtual formatado como ext4. As unidades do Windows são montadas nesse ambiente Linux em /mnt/, portanto sua unidade C: aparece como /mnt/c.
Esse último detalhe é responsável pela maioria das reclamações de desempenho que você lerá sobre WSL. Mais sobre isso abaixo.
Você deve usar WSL ou Windows nativo para Claude Code?
Escolha com base em onde seu projeto fica e se você precisa de sandbox. A documentação de configuração da Anthropic apresenta as três opções diretamente:
| Opção | Requer | Sandbox | Use quando |
|---|---|---|---|
| Windows Nativo | Nada; Git para Windows opcional | Não suportado | Projetos e ferramentas nativos do Windows |
| WSL 2 | WSL 2 habilitado | Suportado | Cadeias de ferramentas Linux, execução em sandbox |
| WSL 1 | WSL 1 habilitado | Não suportado | Apenas se WSL 2 não estiver disponível |
A recomendação honesta: se sua cadeia de compilação ou seus scripts de implantação assumem Linux, execute Claude Code onde o projeto realmente é executado. Um plugin WordPress que é enviado para um servidor LEMP se comporta diferentemente sob PowerShell do que sob bash, e você gastará sua sessão depurando a lacuna em vez do código.
Se você constrói aplicações .NET ou qualquer outra coisa com ferramentas Windows envolvidas, instale nativamente e pule todo este artigo. Ambas as instalações podem coexistir na mesma máquina, portanto um experimento custa apenas espaço em disco.
Como instalar WSL 2 no Windows
Abra o PowerShell como Administrador e execute um comando:
wsl --install
Isso habilita os recursos do Windows necessários e instala Ubuntu como a distribuição padrão, com WSL 2 como a versão padrão. Reinicie quando solicitado. No primeiro lançamento, o terminal Ubuntu solicita um nome de usuário e senha, que são separados de suas credenciais do Windows e usados para sudo dentro do Linux.
Confirme o que você acabou obtendo:
wsl -l -v
A coluna VERSION precisa ler 2. Se ler 1, converta:
wsl --set-version Ubuntu 2
Claude Code precisa do Windows 10 versão 1809 ou mais recente, ou Windows Server 2019 ou mais recente, em uma máquina de 64 bits com pelo menos 4 GB de RAM. O próprio instalador quer aproximadamente 512 MB de memória livre para ser concluído, o que vale saber se você está fazendo isso em um laptop de trabalho com 40 abas de navegador abertas.
Instalando Claude Code dentro do WSL
Execute o instalador Linux dentro do terminal WSL, nunca do PowerShell ou CMD:
curl -fsSL https://claude.ai/install.sh | bash
Este é o mesmo instalador nativo usado em macOS e Linux, e não tem nenhuma dependência Node.js. Ele coloca o binário em ~/.local/bin/claude e atualiza em segundo plano por conta própria.
Então verifique:
claude --version
claude doctor
claude --version imprime algo como 2.1.211 (Claude Code). claude doctor executa um diagnóstico somente leitura de sua instalação e configurações sem iniciar uma sessão, e é a primeira coisa a executar sempre que algo se comporta estranhamente.
Se o shell reportar claude: command not found, o diretório de instalação está faltando do seu PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Você não precisa de Git para Windows aqui. Isso se aplica a instalações nativas do Windows, onde ele habilita a ferramenta Bash. Dentro do WSL você já tem bash.
Um pré-requisito que pega as pessoas na tela de login: Claude Code requer uma conta Pro, Max, Team, Enterprise ou Console. O plano Claude.ai gratuito não inclui isso.
Mantenha seus projetos fora de /mnt/c
Esta é a configuração que decide se WSL se sente rápido ou quebrado, e não está em settings.json. Armazene seus repositórios no sistema de arquivos Linux em /home/<user>/project, não em /mnt/c/Users/<user>/project.
A própria documentação do WSL da Microsoft recomenda contra trabalhar entre sistemas operacionais com seus arquivos. Cada leitura de arquivo em /mnt/c cruza o limite entre a VM do Linux e o sistema de arquivos do Windows, e esse cruzamento tem um custo pago por operação. Claude Code lê muitos arquivos. Ele procura seu código e grep para símbolos antes de escrever uma única linha.
Coloque um repositório em /mnt/c e as buscas ficam lentas o suficiente para que os resultados voltem incompletos enquanto tudo se reporta como saudável. A falha é silenciosa. Você obtém uma sessão Claude Code que parece inexplicavelmente pior em encontrar coisas do que era no Mac do seu colega.
Clone em ~/projects/ e o problema desaparece. Para abrir esse diretório no Explorador de Arquivos do Windows quando necessário:
explorer.exe .
Se você realmente precisa dos arquivos no lado do Windows para um editor nativo do Windows, esse é o sinal para reconsiderar e instalar Claude Code nativamente.
Por que o login do Claude Code falha pela primeira vez em WSL
A primeira execução de claude abre um navegador para autenticação, e em WSL esse navegador abre no host do Windows. O redirecionamento que ele envia de volta não consegue alcançar o servidor de callback escutando dentro da VM do Linux, então o login parece travar.
A correção, de acordo com o guia de solução de problemas de instalação da Anthropic: conclua o login, e o navegador mostra um código de login em vez de redirecionar. Cole esse código no prompt do terminal.
Se o navegador nunca abrir, aponte WSL para seu navegador Windows:
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
Se colar no prompt não fizer nada, o que acontece porque as vinculações de colagem do Windows Terminal variam, use o comando que lê o código da entrada padrão:
claude auth login
A armadilha Node.js que só acontece em WSL
WSL importa o PATH do Windows por padrão, então comandos Linux podem resolver silenciosamente para executáveis do Windows. Execute which node dentro do WSL e verifique a saída. Um caminho começando com /mnt/c/ significa que seu shell Linux está chamando a instalação Node.js do Windows, e as instalações se comportarão de maneiras que não fazem sentido.
Isso só o afeta se você instalou Claude Code através do npm dentro do WSL, onde o sintoma é exec: node: not found. Instale Node através do gerenciador de pacotes de sua distribuição ou nvm, e adicione o carregador nvm a ~/.bashrc para que vença a corrida PATH:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
O caminho mais simples é pular npm completamente. O instalador nativo baixa um binário que nunca invoca Node em tempo de execução, o que remove toda essa categoria de problema. Se você usar npm, o pacote exigiu Node.js 22 ou posterior desde v2.1.198.
Resista à tentação de corrigir a vazão de PATH definindo appendWindowsPath = false em /etc/wsl.conf. O guia de solução de problemas da Anthropic sinaliza isso explicitamente: quebra sua capacidade de chamar executáveis Windows de WSL, incluindo o truque do navegador acima.
WSL 1 e o erro de formato executável
Se claude imprimir cannot execute binary file: Exec format error, você está em WSL 1. Os cabeçalhos de programa do binário nativo mudaram de uma forma que o carregador WSL 1 não consegue lidar, rastreado como problema #38788 no repositório Claude Code.
Converta a distribuição do PowerShell:
wsl --set-version Ubuntu 2
Se alguma restrição o forçar a ficar em WSL 1, você pode invocar o binário através do vinculador dinâmico adicionando uma função shell a ~/.bashrc:
claude() {
/lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}
Isso funciona, embora possa uma regressão conhecida e não seja uma configuração suportada. WSL 1 também não obtém sandbox.
O que carrega da configuração macOS
Tudo acima dessa linha é encanamento específico do Windows. Tudo abaixo é idêntico a qualquer outra plataforma, que é o argumento real para WSL: uma vez que você está dentro, você está em Linux.
oh-my-zsh instala com o mesmo script. /terminal-setup configura Shift+Enter e o seletor de arquivo @ da mesma forma, e /statusline constrói a mesma exibição de custo e limite de taxa. As configurações de Claude Code que vale a pena alterar são as mesmas, e as dicas de fluxo de trabalho Claude Code se aplicam sem modificação.
A única diferença é qual arquivo você edita. Em WSL você geralmente está em bash, então aliases vão em ~/.bashrc em vez de ~/.zshrc, a menos que você instale zsh e o defina como seu shell de login:
alias cc="claude"
alias ccc="claude --continue"
Então qual você deve instalar?
A decisão se resume a duas perguntas. Seu projeto assume Linux? Instale dentro do WSL 2. Você precisa de execução de comando em sandbox? WSL 2 é a única opção no Windows que suporta isso.
Caso contrário, instale nativamente do PowerShell, adicione Git para Windows se quiser a ferramenta Bash, e continue com seu trabalho. O caminho nativo tem menos partes móveis, e menos partes móveis significa menos coisas que quebram silenciosamente.
E se você instalar WSL 2 e levar uma coisa deste artigo, que seja a regra do sistema de arquivos. Todos os outros problemas aqui se anunciam com uma mensagem de erro. Esse apenas torna Claude Code pior e nunca diz por quê.
Se você está padronizando um ambiente de desenvolvimento em um time onde algumas máquinas executam Windows e outras não, e a diferença está começando a custar sprints, esse é o tipo de decisão na qual sou chamado para ajudar.