WSL2 bem configurado: ajustes que uso no dia a dia para desenvolvimento

O WSL2 já funciona muito bem com a configuração padrão, mas alguns ajustes fazem diferença quando ele passa a ser parte do ambiente de desenvolvimento do dia a dia.

Para quem trabalha com PHP, Node.js, Docker, bancos de dados, servidores locais e diversas ferramentas Linux, vale a pena entender principalmente dois arquivos:

.wslconfig
/etc/wsl.conf

Eles têm finalidades diferentes e essa distinção evita muita confusão.

`.wslconfig` x `/etc/wsl.conf`

O .wslconfig controla configurações globais do WSL2 e fica no perfil do usuário do Windows:

text

C:\Users\SEU_USUARIO\.wslconfig

Já o /etc/wsl.conf controla configurações específicas de uma distribuição Linux:

text

/etc/wsl.conf

Em outras palavras:

Arquivo	Escopo	Exemplos
`.wslconfig`	Global para o WSL2	Memória, CPU, swap, rede
`/etc/wsl.conf`	Uma distribuição	systemd, automount, hosts, usuário

Essa separação é importante porque é comum encontrar configurações dos dois arquivos misturadas em um único exemplo.

1. Limitando memória e processadores

No meu .wslconfig, uma configuração que considero útil é limitar explicitamente os recursos disponíveis para o WSL:

ini

[wsl2]

memory=16GB
processors=8
swap=2GB

A ideia não é simplesmente dar o máximo de recursos disponíveis para o Linux.

O WSL compartilha os recursos da máquina com o Windows e outras aplicações. Definir limites explícitos ajuda a manter o ambiente previsível, principalmente quando existem ferramentas pesadas rodando simultaneamente.

`memory`

ini

memory=16GB

Define o limite de memória da máquina virtual utilizada pelo WSL2.

O valor ideal depende da quantidade de RAM disponível no computador e do tipo de trabalho realizado.

Para desenvolvimento, o importante é encontrar um equilíbrio entre:

ferramentas Linux;
IDE;
navegador;
Docker;
banco de dados;
ferramentas de IA;
aplicações do próprio Windows.

Não existe um valor universal.

`processors`

ini

processors=8

Define quantos processadores lógicos podem ser utilizados pela VM do WSL2.

Isso pode ser interessante em máquinas com muitos núcleos, evitando que um conjunto de processos dentro do WSL consuma todos os recursos disponíveis.

`swap`

ini

swap=2GB

Define o tamanho do arquivo de swap utilizado pelo WSL2.

Swap não substitui RAM, mas funciona como uma camada adicional quando a memória física disponível é insuficiente.

Prefiro manter uma quantidade relativamente pequena em uma máquina de desenvolvimento, mas esse valor também depende do uso.

2. Modo de rede espelhado

Outra configuração que deixo disponível, mas nem sempre ativo, é:

ini

[wsl2]

networkingMode=mirrored

O modo mirrored muda a arquitetura de rede utilizada pelo WSL2 para espelhar as interfaces de rede do Windows.

Entre os benefícios documentados pela Microsoft estão suporte a IPv6, melhor compatibilidade com VPNs, multicast e a possibilidade de acessar o WSL diretamente pela LAN em cenários apropriados.

Por isso, no meu arquivo costumo deixar a opção comentada:

ini

# networkingMode=mirrored

Assim posso ativá-la rapidamente quando preciso.

Esse recurso é especialmente interessante em ambientes em que existem:

VPNs corporativas;
múltiplas interfaces de rede;
serviços locais que precisam ser acessados de outros dispositivos;
cenários onde a rede NAT padrão do WSL causa alguma limitação.

Antes de habilitar o modo espelhado, vale verificar se ele realmente resolve uma necessidade do seu ambiente.

3. Habilitando o systemd

Essa configuração pertence ao /etc/wsl.conf, dentro da distribuição Linux.

ini

[boot]
systemd=true

O systemd é importante quando queremos utilizar serviços Linux de forma mais próxima de uma instalação tradicional.

Por exemplo:

bash

systemctl status

ou:

bash

systemctl list-unit-files --type=service

Isso facilita bastante ambientes que dependem de serviços como:

Docker;
bancos de dados;
Redis;
serviços auxiliares;
outras aplicações que utilizam systemd.

Depois de alterar o wsl.conf, normalmente é necessário reiniciar a instância do WSL.

No Windows:

powershell

wsl --shutdown

Depois disso, ao abrir novamente a distribuição, a configuração será carregada.

4. Mantendo um `/etc/hosts` personalizado

Outra configuração que gosto de usar é:

ini

[network]
generateHosts=false

Por padrão, o WSL pode gerar automaticamente o arquivo /etc/hosts.

Quando essa opção é desabilitada, o WSL deixa de fazer essa geração automática, permitindo que a distribuição mantenha um arquivo /etc/hosts próprio.

Isso é útil em ambientes de desenvolvimento que utilizam vários domínios locais.

Por exemplo:

text

127.0.0.1 app.local
127.0.0.1 api.local
127.0.0.1 admin.local

Isso pode ser interessante quando existe uma estrutura de desenvolvimento com:

múltiplas aplicações;
reverse proxy;
virtual hosts;
Traefik;
Apache;
Nginx;
domínios locais.

5. Permissões de arquivos no `/mnt`

Aqui entra uma configuração que pode fazer bastante diferença quando trabalhamos com arquivos do Windows dentro do Linux.

Por padrão, o WSL monta unidades como:

text

/mnt/c
/mnt/d

através do DrvFs.

No /etc/wsl.conf, podemos definir opções adicionais de montagem:

ini

[automount]
options="metadata"

O metadata permite armazenar metadados de permissões Linux nos arquivos do Windows montados pelo WSL.

Isso ajuda quando precisamos trabalhar com comandos Linux que dependem de permissões de arquivos.

6. Usando `umask` e `fmask`

Uma configuração que também pode ser utilizada é:

ini

[automount]
options="metadata,umask=022,fmask=011"

As máscaras controlam quais permissões serão removidas dos arquivos e diretórios.

Por exemplo:

text

umask=022

é uma configuração bastante comum porque normalmente resulta em diretórios com comportamento semelhante a:

text

Enquanto o fmask pode ser usado para aplicar uma máscara específica aos arquivos.

Uma diferença importante é:

umask afeta arquivos e diretórios;
fmask afeta arquivos;
dmask pode ser usado especificamente para diretórios.

A documentação do WSL também observa que essas opções de máscara dependem do uso de metadata.

Uma observação importante

No arquivo final, não coloque duas seções [automount] diferentes como em alguns exemplos encontrados na internet.

Prefira uma única seção:

ini

[automount]
options="metadata,umask=022,fmask=011"

Ou, caso você não precise das máscaras:

ini

[automount]
options="metadata"

Os dois exemplos são alternativas.

7. Minha configuração base

Separando corretamente as configurações entre os dois arquivos, uma configuração próxima da que uso fica assim.

`%UserProfile%\.wslconfig`

ini

[wsl2]

memory=16GB
processors=8
swap=2GB

# Ative quando fizer sentido para seu ambiente de rede
# networkingMode=mirrored

`/etc/wsl.conf`

ini

[boot]
systemd=true

[network]
generateHosts=false

[automount]
options="metadata,umask=022,fmask=011"

A vantagem de separar dessa forma é saber exatamente o que é uma configuração global do WSL2 e o que pertence à distribuição Linux.

8. Um detalhe importante sobre desempenho

Existe outro ajuste que considero ainda mais importante do que várias opções do .wslconfig: onde os projetos estão armazenados.

Se o principal conjunto de ferramentas utilizado no projeto roda dentro do Linux, prefiro manter os projetos no filesystem Linux:

text

/home/fernando/projects

em vez de:

text

/mnt/c/Users/Fernando/projects

A recomendação oficial da Microsoft é manter os arquivos no mesmo sistema operacional das ferramentas que os utilizam com maior frequência.

Por exemplo, ferramentas Linux como:

bash

git
npm
composer
php
make

tendem a funcionar melhor quando o projeto está no filesystem Linux.

Isso pode fazer diferença principalmente em projetos com milhares de arquivos, como:

text

node_modules
vendor
.git
cache
build

Quando preciso abrir os arquivos pelo Windows Explorer, posso fazer isso diretamente pelo WSL:

bash

explorer.exe .

Assim consigo manter os arquivos no filesystem Linux sem abrir mão da integração com o Windows.

9. Como aplicar alterações

Quando alterar o .wslconfig ou /etc/wsl.conf, não basta simplesmente fechar a janela do terminal.

Uma forma prática de reiniciar o WSL é:

powershell

wsl --shutdown

Depois:

powershell

wsl

Também é possível verificar se existem distribuições ainda em execução:

powershell

wsl --list --running

Esse detalhe é importante porque alterações de configuração só entram em vigor quando a instância do WSL é reiniciada.

10. Como verificar a configuração

Depois de reiniciar, gosto de verificar rapidamente o ambiente.

Memória

bash

free -h

CPUs

bash

nproc

Systemd

bash

systemctl is-system-running

Montagens

bash

mount | grep /mnt

Distribuições instaladas

No Windows:

powershell

wsl --list --verbose

Versão do WSL

powershell

wsl --version

Isso ajuda a diferenciar um problema de configuração de um problema relacionado à versão do próprio WSL.

11. O que realmente vale a pena configurar?

Não existe uma configuração universalmente correta para WSL2.

Minha abordagem é começar com o mínimo necessário e adicionar ajustes conforme o ambiente exige.

Normalmente penso em quatro categorias:

Recursos

ini

memory=16GB
processors=8
swap=2GB

Serviços Linux

ini

[boot]
systemd=true

Rede

ini

[network]
generateHosts=false

ou:

ini

networkingMode=mirrored

Arquivos

ini

[automount]
options="metadata,umask=022,fmask=011"

O objetivo não é ter o maior número possível de configurações.

É ter um ambiente previsível para o trabalho que realmente será executado nele.

Conclusão

O WSL2 funciona muito bem com os valores padrão, mas entender seus arquivos de configuração permite adaptar o ambiente ao seu fluxo de trabalho.

Para mim, os principais pontos são:

controlar quanto de CPU e memória o WSL pode utilizar;
habilitar systemd quando o projeto precisa de serviços Linux;
controlar como o /etc/hosts é gerenciado;
ajustar permissões dos discos Windows montados no Linux;
usar o modo mirrored quando a rede NAT padrão não atende ao cenário;
manter projetos no filesystem Linux quando as principais ferramentas são executadas dentro do WSL.

Mais importante do que copiar uma configuração pronta é entender o motivo de cada opção.

O melhor .wslconfig é aquele que resolve as necessidades da sua máquina e do seu ambiente de desenvolvimento.

A divisão entre .wslconfig e /etc/wsl.conf, o suporte ao systemd, generateHosts, metadata, máscaras de permissão e o comportamento do modo mirrored seguem a documentação atual da Microsoft. :contentReference[oaicite:1]

A recomendação sobre manter projetos no filesystem Linux quando as ferramentas principais são Linux também é documentada pela Microsoft, especialmente por questões de desempenho de I/O.

.wslconfig x /etc/wsl.conf

1. Limitando memória e processadores

memory

processors

swap

2. Modo de rede espelhado

3. Habilitando o systemd

4. Mantendo um /etc/hosts personalizado

5. Permissões de arquivos no /mnt

6. Usando umask e fmask

Uma observação importante

7. Minha configuração base

%UserProfile%\.wslconfig

/etc/wsl.conf

8. Um detalhe importante sobre desempenho

9. Como aplicar alterações

10. Como verificar a configuração

Memória

CPUs

Systemd

Montagens

Distribuições instaladas

Versão do WSL

11. O que realmente vale a pena configurar?

Recursos

Serviços Linux

Rede

Arquivos

Conclusão

`.wslconfig` x `/etc/wsl.conf`

`memory`

`processors`

`swap`

4. Mantendo um `/etc/hosts` personalizado

5. Permissões de arquivos no `/mnt`

6. Usando `umask` e `fmask`

`%UserProfile%\.wslconfig`

`/etc/wsl.conf`