Em 2010, publiquei um livro sobre como fazer Windows e Linux conversarem numa rede. Na época, compartilhar uma pasta entre os dois era projeto de fim de semana, com arquivo de configuração e muita paciência. Dezesseis anos depois, o Windows traz um Linux dentro dele e você instala com um comando só. Nunca foi tão fácil usar terminal no Windows, e até rodar aplicativo Linux lá dentro.
Então, pra quem está configurando o Claude Code no Windows em 2026, a resposta é: o WSL não é mais obrigatório. O Claude Code roda nativamente no Windows 10 versão 1809 ou mais novo. Instale dentro do WSL 2 quando o seu projeto depender de ferramentas Linux, ou quando você quiser execução de comandos em sandbox, que, segundo a documentação de configuração da Anthropic, funciona no WSL 2 e em nenhum outro lugar do Windows.
A maioria dos guias de WSL ainda circulando foi escrita quando essa escolha não existia. Alguns dizem com todas as letras que a Anthropic não tem versão nativa pra Windows. Isso deixou de ser verdade.
Este post continua o de configuração do Claude Code no macOS, e quase toda aquela configuração vale aqui sem mudança.
O que é o WSL, afinal
O WSL 2 é um kernel Linux de verdade rodando numa máquina virtual leve que a Microsoft distribui com o Windows. O sistema de arquivos do Linux fica dentro de um disco virtual formatado em ext4. Os drives do Windows aparecem montados nesse Linux em /mnt/, então o seu C: vira /mnt/c.
Esse último detalhe responde pela maioria das reclamações de desempenho que você vai ler sobre o WSL. Já falo disso.
WSL ou Windows nativo pro Claude Code?
Escolha pelo lugar onde o seu projeto mora e pela necessidade de sandbox. A documentação de configuração da Anthropic apresenta as três opções assim:
| Opção | Precisa de | Sandbox | Use quando |
|---|---|---|---|
| Windows nativo | Nada; Git for Windows opcional | Não suportado | Projetos e ferramentas do Windows |
| WSL 2 | WSL 2 ativado | Suportado | Ferramentas Linux, execução em sandbox |
| WSL 1 | WSL 1 ativado | Não suportado | Só se o WSL 2 não estiver disponível |
A recomendação honesta: se o seu build ou os seus scripts de deploy partem do princípio de que é Linux, rode o Claude Code onde o projeto roda de fato. Um plugin WordPress que vai pra um servidor LEMP se comporta de um jeito no PowerShell e de outro no bash, e você vai passar a sessão depurando essa diferença em vez do código.
Se você compila aplicação .NET, ou qualquer coisa que envolva ferramentas do Windows, instale nativo e pule este artigo inteiro. As duas instalações convivem na mesma máquina, então testar só custa espaço em disco.
Como instalar o WSL 2 no Windows
Abra o PowerShell como Administrador e rode um comando:
wsl --install
Isso ativa os recursos necessários do Windows e instala o Ubuntu como distribuição padrão, com o WSL 2 como versão padrão. Reinicie quando pedir. Na primeira vez que abrir, o terminal do Ubuntu pede um usuário e uma senha, que são separados das suas credenciais do Windows e servem pro sudo dentro do Linux.
Confira o que você ficou tendo:
wsl -l -v
A coluna VERSION precisa mostrar 2. Se mostrar 1, converta:
wsl --set-version Ubuntu 2
O Claude Code precisa do Windows 10 versão 1809 ou mais novo, ou do Windows Server 2019 ou mais novo, numa máquina de 64 bits com pelo menos 4 GB de RAM. O instalador quer uns 512 MB de memória livre pra terminar, o que é bom saber se você está fazendo isso num notebook de trabalho com 40 abas abertas no navegador.
Instalando o Claude Code dentro do WSL
Rode o instalador de Linux dentro do terminal do WSL, nunca no PowerShell ou no CMD:
curl -fsSL https://claude.ai/install.sh | bash
É o mesmo instalador nativo do macOS e do Linux, e não depende de Node.js. Ele coloca o binário em ~/.local/bin/claude e se atualiza sozinho em segundo plano.
Depois confira:
claude --version
claude doctor
O claude --version imprime algo como 2.1.211 (Claude Code). O claude doctor faz um diagnóstico só de leitura da instalação e das configurações, sem abrir sessão, e é a primeira coisa a rodar sempre que algo se comportar estranho.
Se o shell responder claude: command not found, falta a pasta de instalação no PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Aqui você não precisa do Git for Windows. Ele serve pras instalações nativas no Windows, onde ativa a ferramenta Bash. Dentro do WSL você já tem bash.
Um pré-requisito que pega gente na tela de login: o Claude Code exige conta Pro, Max, Team, Enterprise ou Console. O plano gratuito do Claude.ai não inclui.
Mantenha os projetos fora do /mnt/c
É essa configuração que decide se o WSL fica rápido ou quebrado, e ela não está no settings.json. Guarde os repositórios no sistema de arquivos do Linux, em /home/<usuario>/projeto, e não em /mnt/c/Users/<usuario>/projeto.
A própria documentação do WSL da Microsoft recomenda não trabalhar com os arquivos de um sistema a partir do outro. Toda leitura de arquivo em /mnt/c atravessa a fronteira entre a VM do Linux e o sistema de arquivos do Windows, e essa travessia tem um custo por operação. O Claude Code lê muito arquivo. Ele vasculha o código e procura símbolos antes de escrever uma única linha.
Coloque um repositório em /mnt/c e as buscas ficam tão lentas que os resultados voltam incompletos, enquanto tudo diz que está saudável. A falha é silenciosa. Você fica com uma sessão do Claude Code inexplicavelmente pior pra achar as coisas do que no Mac do seu colega.
Clone em ~/projects/ e o problema some. Pra abrir essa pasta no Explorador de Arquivos do Windows quando precisar:
explorer.exe .
Se você precisa mesmo que os arquivos fiquem do lado do Windows pra usar um editor do Windows, esse é o sinal pra repensar e instalar o Claude Code nativo.
Por que o login do Claude Code falha na primeira vez no WSL
Na primeira vez que você roda claude, ele abre um navegador pra autenticar, e no WSL esse navegador abre no Windows. O redirecionamento que ele manda de volta não consegue chegar ao servidor de callback que está escutando dentro da VM do Linux, então o login parece travar.
A correção, segundo o guia de solução de problemas de instalação da Anthropic: termine o login, e o navegador mostra um código em vez de redirecionar. Cole esse código no terminal.
Se o navegador nem abrir, aponte o WSL pro navegador do Windows:
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
Se colar no terminal não fizer nada (acontece, porque os atalhos de colar do Windows Terminal variam), use o comando que lê o código da entrada padrão:
claude auth login
A armadilha do Node.js que só acontece no WSL
O WSL importa o PATH do Windows por padrão, então comandos do Linux podem, sem aviso, cair em executáveis do Windows. Rode which node dentro do WSL e olhe a saída. Um caminho começando com /mnt/c/ quer dizer que o seu shell Linux está chamando o Node.js do Windows, e as instalações vão se comportar de jeitos que não fazem sentido.
Isso só te afeta se você instalou o Claude Code pelo npm dentro do WSL, e o sintoma é exec: node: not found. Instale o Node pelo gerenciador de pacotes da distribuição ou pelo nvm, e coloque o carregador do nvm no ~/.bashrc pra ele ganhar a disputa do PATH:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
O caminho mais simples é pular o npm de vez. O instalador nativo baixa um binário que nunca chama o Node pra rodar, o que elimina essa categoria inteira de problema. Se você usa npm, o pacote exige Node.js 22 ou mais novo desde a v2.1.198.
Resista à tentação de resolver o vazamento de PATH com appendWindowsPath = false no /etc/wsl.conf. O guia de solução de problemas da Anthropic avisa isso explicitamente: quebra a sua capacidade de chamar executáveis do Windows a partir do WSL, inclusive o truque do navegador acima.
WSL 1 e o erro Exec format error
Se o claude imprime cannot execute binary file: Exec format error, você está no WSL 1. Os cabeçalhos de programa do binário nativo mudaram de um jeito que o carregador do WSL 1 não entende, registrado como issue #38788 no repositório do Claude Code.
Converta a distribuição pelo PowerShell:
wsl --set-version Ubuntu 2
Se alguma restrição te obrigar a ficar no WSL 1, dá pra chamar o binário pelo linker dinâmico, com uma função de shell no ~/.bashrc:
claude() {
/lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}
Funciona, mas é remendo pra uma regressão conhecida, e não uma configuração suportada. O WSL 1 também fica sem sandbox.
O que vem da configuração do macOS
Tudo acima desta linha é encanamento específico do Windows. Tudo abaixo é igual em qualquer plataforma, e é esse o argumento de verdade a favor do WSL: lá dentro, você está no Linux.
O oh-my-zsh instala com o mesmo script. O /terminal-setup configura o Shift+Enter e o seletor de arquivos com @ do mesmo jeito, e o /statusline monta a mesma exibição de custo e rate limit. As configurações do Claude Code que valem a pena mudar são as mesmas, e as dicas de fluxo de trabalho com Claude Code valem sem ajuste.
A única diferença é o arquivo que você edita. No WSL você normalmente está no bash, então os aliases vão no ~/.bashrc em vez do ~/.zshrc, a não ser que instale o zsh e defina como shell de login:
alias cc="claude"
alias ccc="claude --continue"
Então, qual instalar?
A decisão se resume a duas perguntas. O seu projeto parte do princípio de que é Linux? Instale dentro do WSL 2. Você precisa de execução de comandos em sandbox? O WSL 2 é a única opção no Windows que suporta isso.
Fora isso, instale nativo pelo PowerShell, acrescente o Git for Windows se quiser a ferramenta Bash e vá trabalhar. O caminho nativo tem menos peças, e menos peças quer dizer menos coisa quebrando em silêncio.
E se você instalar o WSL 2 e levar uma coisa só deste artigo, que seja a regra do sistema de arquivos. Todos os outros problemas daqui se anunciam com mensagem de erro. Esse só deixa o Claude Code pior e nunca diz por quê.
Se você está padronizando o ambiente de desenvolvimento de um time em que algumas máquinas rodam Windows e outras não, e essa diferença começou a custar sprints, essa decisão faz parte do meu trabalho como CTO fracionado. Me conta o que o seu time roda hoje.