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
O Claude in Chrome não é suportado no WSL
Se você rodou claude --chrome ou /chrome dentro do WSL e recebeu o aviso de que o Claude in Chrome não é suportado no WSL ("Claude in Chrome is not supported in WSL"), não tem nada errado na sua configuração. A documentação da integração com o Chrome diz com todas as letras: funciona com Chrome e Edge, e não é suportada no Windows Subsystem for Linux.
A documentação não explica o motivo, mas mostra onde fica cada metade. A extensão Claude in Chrome roda no navegador do Windows e acha o Claude Code por um native messaging host, que o Chrome do Windows procura no registro. O Claude Code dentro do WSL é um programa Linux, então ele se registra onde um Chrome de Linux iria procurar, e o Chrome do Windows nunca fica sabendo. As versões mais antigas eram mais secas: Claude in Chrome Native Host not supported on this platform.
Então, se automatizar o navegador faz parte do seu trabalho (testar uma aplicação local, ler erro de console, preencher formulário), essa parte fica com uma instalação nativa no Windows. Instale o Claude Code pelo PowerShell, entre com /login e rode claude --chrome por lá. O WSL continua cuidando do lado Linux. As duas instalações convivem na mesma máquina.
Com isso, o navegador vira o terceiro motivo pra escolher o Windows nativo, junto com os dois da tabela de comparação lá no começo. Se você precisa mais do navegador do que das ferramentas Linux, comece pelo nativo.
WSL sessions are not available because this device is managed by your organization
Essa mensagem ("as sessões WSL não estão disponíveis porque este dispositivo é gerenciado pela sua organização") vem do app de desktop do Claude, não do Claude Code de linha de comando que este artigo instala. A aba Code do app de desktop consegue rodar uma sessão dentro de uma distribuição WSL 2, e a documentação do WSL no app de desktop diz que, em máquinas gerenciadas por uma empresa, essas sessões podem ficar indisponíveis, e que quem controla isso é o administrador.
Ou seja: não tem nada quebrado na sua máquina e não falta configuração nenhuma. É uma política do notebook da empresa, e você tem dois caminhos:
- Peça pro TI liberar as sessões WSL na sua máquina. O administrador controla isso pelas mesmas configurações gerenciadas que definem o resto do Claude Desktop. Não saia caçando a chave de registro pra mudar por conta própria: em máquina gerenciada, contornar política é conversa com o time de segurança marcada pra acontecer.
- Rode o Claude Code de linha de comando dentro do WSL, que é a configuração deste artigo. É uma instalação separada das sessões WSL do app de desktop. Mas o notebook continua sendo da empresa, então confira o que a sua organização permite antes de usar uma ferramenta pra contornar a política de outra.
Claude requires Windows 10 version 2004 or later
Aqui duas exigências diferentes costumam se misturar. A documentação de instalação do app de desktop pede Windows 10 build 19041 (versão 2004) ou mais novo, incluindo o Windows 11, pro Cowork, o espaço de trabalho de agente do app, que roda numa máquina virtual no seu PC. O wsl --install de um comando só, da Microsoft, exige a mesma versão 2004. Já o Claude Code em si pede menos: Windows 10 versão 1809 ou mais novo, o requisito que aparece na seção de instalação lá em cima.
Se essa mensagem apareceu pra você:
- Confira a versão do Windows com
winver. Qualquer coisa anterior à 2004 está sem suporte há anos, e a correção de verdade é atualizar pro Windows 10 22H2 ou pro Windows 11. - Se você só precisa do Claude Code, nem precisa do app de desktop. A instalação nativa pelo PowerShell roda na 1809, e com o Windows na 2004 ou mais novo o caminho pelo WSL 2 deste artigo também funciona.
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.
