Guia de Configuracao - Windows (WSL2)

Idioma: Portugues (BR) | English | Espanol

Este guia cobre a configuracao completa de um ambiente de desenvolvimento no Windows 10/11 utilizando o WSL2 (Windows Subsystem for Linux). Com o WSL2, voce tera um ambiente Linux real rodando dentro do Windows, com acesso total as mesmas ferramentas do guia Linux.

Dica: O WSL2 roda um kernel Linux real, diferente do WSL1 que era apenas uma camada de compatibilidade. O desempenho e significativamente melhor, especialmente para operacoes de I/O e Docker.

1. Pre-requisitos

Requisitos de Sistema

Windows 10 versao 2004 ou superior (Build 19041+)
Windows 11 qualquer versao
Virtualizacao habilitada na BIOS/UEFI
Conta de administrador no Windows

Verificar Versao do Windows

Pressione Win + R, digite winver e pressione Enter. Verifique se sua versao atende aos requisitos.

Habilitar Virtualizacao

Se a virtualizacao nao estiver habilitada, reinicie o computador, entre na BIOS/UEFI e ative:

Intel: VT-x ou Intel Virtualization Technology
AMD: AMD-V ou SVM Mode

2. WSL2

2.1 Instalar o WSL2

Abra o PowerShell como Administrador e execute:

wsl --install

Este comando automaticamente:

Habilita o recurso WSL
Habilita a Plataforma de Maquina Virtual
Baixa e instala o kernel Linux mais recente
Define WSL2 como versao padrao
Instala a distribuicao Ubuntu (padrao)

Aviso: Reinicie o computador apos a instalacao.

2.2 Escolher uma Distribuicao

Por padrao, o wsl --install instala o Ubuntu. Para ver outras opcoes:

# Listar distribuicoes disponiveis
wsl --list --online

# Instalar uma distribuicao especifica
wsl --install -d Ubuntu-24.04

Instalar Fedora no WSL2 (Opcional)

O Fedora nao esta disponivel oficialmente no WSL, mas pode ser instalado via comunidade:

# Opcao 1: Via Microsoft Store - Procure por "Fedora WSL" ou "Fedora Remix for WSL"

# Opcao 2: Via COPR (dentro do WSL com outra distro)
# Consulte: https://github.com/fedora-cloud/docker-brew-fedora

2.3 Configuracao Inicial do WSL2

Na primeira inicializacao, crie seu usuario e senha Linux:

# O WSL vai pedir para criar um usuario e senha
# Apos criar, atualize o sistema
sudo apt update && sudo apt upgrade -y

2.4 Configurar Recursos do WSL2 (Opcional)

Crie ou edite o arquivo .wslconfig no Windows para controlar os recursos:

Abra o Bloco de Notas e salve em C:\Users\SeuUsuario\.wslconfig:

[wsl2]
memory=8GB
processors=4
swap=4GB
localhostForwarding=true

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true

Dica: Ajuste memory e processors conforme os recursos do seu computador. Uma boa regra e alocar metade da RAM e metade dos nucleos.

Apos criar o arquivo, reinicie o WSL:

wsl --shutdown

3. Windows Terminal

3.1 Instalar

O Windows Terminal e o melhor emulador de terminal para Windows. Instale pela Microsoft Store:

Abra a Microsoft Store
Pesquise por "Windows Terminal"
Clique em Instalar

Ou via PowerShell:

winget install Microsoft.WindowsTerminal

3.2 Configurar Aparencia

Abra o Windows Terminal e acesse as configuracoes (Ctrl + ,):

Perfil padrao: Selecione Ubuntu (ou sua distro WSL) como perfil padrao
Fonte: Selecione JetBrainsMono Nerd Font (instale primeiro, veja a secao Fonte)
Tamanho da fonte: 14
Esquema de cores: One Half Dark ou GitHub Dark (ou importe um personalizado)
Transparencia: Ative efeito acrilico se desejar (Aparencia > Efeitos de transparencia)

3.3 Configuracao via JSON (Opcional)

Para configuracao manual, clique em Abrir arquivo JSON nas configuracoes e ajuste:

{
  "profiles": {
    "defaults": {
      "font": {
        "face": "JetBrainsMono Nerd Font",
        "size": 14
      },
      "opacity": 95,
      "useAcrylic": true
    }
  }
}

4. Fish Shell

Todos os comandos a partir daqui devem ser executados dentro do terminal WSL2 (Ubuntu).

4.1 Instalar o Fish

sudo apt-add-repository ppa:fish-shell/release-4
sudo apt update
sudo apt install -y fish

4.2 Definir como Shell Padrao

# Verificar onde o fish esta instalado
which fish

# Adicionar a lista de shells validos
echo $(which fish) | sudo tee -a /etc/shells

# Definir como shell padrao
chsh -s $(which fish)

Aviso: Feche e reabra o terminal WSL para a mudanca ter efeito.

4.3 Instalar o Starship

curl -sS https://starship.rs/install.sh | sh

4.4 Configurar o Fish

mkdir -p ~/.config/fish

Crie o arquivo ~/.config/fish/config.fish com o seguinte conteudo:

# ============================================================
# Fish Shell Configuration
# ============================================================

# --- Prompt ---
starship init fish | source

# --- Version Manager ---
mise activate fish | source

# --- Smart Navigation ---
zoxide init fish | source

# --- Fuzzy Finder ---
fzf --fish | source

# --- Aliases (eza) ---
alias lz "eza --color=always --long --no-filesize --icons=always --no-time --no-user --no-permissions"
alias lsz "eza --color=always --long --no-filesize --icons=always --no-time --no-user -la"
alias lt "eza --tree --icons"

# --- PATH ---
export PATH="$HOME/.local/bin:$PATH"

5. Docker Desktop

5.1 Instalar o Docker Desktop

No Windows, baixe e instale o Docker Desktop:

Acesse https://www.docker.com/products/docker-desktop/
Baixe o instalador para Windows
Execute o instalador e siga as instrucoes

Ou via PowerShell:

winget install Docker.DockerDesktop

5.2 Habilitar Integracao com WSL2

Abra o Docker Desktop
Va em Settings (icone de engrenagem)
Em General, certifique-se de que "Use the WSL 2 based engine" esta marcado
Em Resources > WSL Integration:
- Ative a integracao com sua distribuicao (ex: Ubuntu)
- Clique em Apply & Restart

5.3 Verificar no WSL2

Abra o terminal WSL e teste:

docker --version
docker compose version
docker run hello-world

Dica: Com a integracao WSL2, voce nao precisa instalar o Docker dentro do Linux. O Docker Desktop do Windows compartilha o daemon com o WSL2 automaticamente.

6. Visual Studio Code

6.1 Instalar no Windows

Baixe e instale o VS Code no Windows (nao dentro do WSL):

winget install Microsoft.VisualStudioCode

Ou baixe de https://code.visualstudio.com/.

6.2 Instalar Extensao WSL

Instale a extensao WSL (anteriormente chamada "Remote - WSL"):

code --install-extension ms-vscode-remote.remote-wsl

6.3 Abrir Projetos do WSL2

A partir do terminal WSL, abra qualquer pasta no VS Code:

# Navegar ate o projeto
cd ~/Projects/meu-projeto

# Abrir no VS Code
code .

O VS Code vai abrir no Windows com conexao remota ao WSL2. Voce vera WSL: Ubuntu no canto inferior esquerdo.

6.4 Importar Configuracoes e Extensoes

Com o VS Code aberto via WSL, instale as extensoes. Dentro do terminal WSL:

code \
  --install-extension ms-python.python \
  --install-extension ms-python.vscode-pylance \
  --install-extension ms-python.debugpy \
  --install-extension ms-python.isort \
  --install-extension ms-python.pylint \
  --install-extension ms-python.mypy-type-checker \
  --install-extension ms-python.vscode-python-envs \
  --install-extension ms-vscode.vscode-typescript-next \
  --install-extension golang.go \
  --install-extension bmewburn.vscode-intelephense-client \
  --install-extension zobo.php-intellisense \
  --install-extension mehedidracula.php-constructor \
  --install-extension phproberto.vscode-php-getters-setters \
  --install-extension robberphex.php-debug \
  --install-extension vue.volar \
  --install-extension prisma.prisma \
  --install-extension batisteo.vscode-django \
  --install-extension bradlc.vscode-tailwindcss \
  --install-extension csstools.postcss \
  --install-extension digitalbrainstem.javascript-ejs-support \
  --install-extension zignd.html-css-class-completion \
  --install-extension william-voyek.vscode-nginx \
  --install-extension redhat.vscode-xml \
  --install-extension redhat.vscode-yaml \
  --install-extension mikestead.dotenv \
  --install-extension docker.docker \
  --install-extension ms-vscode-remote.remote-containers \
  --install-extension ms-vscode-remote.remote-ssh \
  --install-extension ms-vscode-remote.remote-ssh-edit \
  --install-extension ms-vscode-remote.vscode-remote-extensionpack \
  --install-extension ms-vscode.remote-explorer \
  --install-extension ms-vscode.remote-repositories \
  --install-extension ms-vscode.remote-server \
  --install-extension ms-kubernetes-tools.vscode-kubernetes-tools \
  --install-extension github.codespaces \
  --install-extension github.remotehub \
  --install-extension eamodio.gitlens \
  --install-extension donjayamanne.githistory \
  --install-extension mhutchie.git-graph \
  --install-extension github.vscode-pull-request-github \
  --install-extension github.vscode-github-actions \
  --install-extension github.copilot \
  --install-extension github.copilot-chat \
  --install-extension esbenp.prettier-vscode \
  --install-extension dbaeumer.vscode-eslint \
  --install-extension editorconfig.editorconfig \
  --install-extension firsttris.vscode-jest-runner \
  --install-extension orta.vscode-jest \
  --install-extension vitest.explorer \
  --install-extension antfu.vite \
  --install-extension github.github-vscode-theme \
  --install-extension dracula-theme.theme-dracula \
  --install-extension pkief.material-icon-theme \
  --install-extension naumovs.color-highlight \
  --install-extension oderwat.indent-rainbow \
  --install-extension alefragnani.bookmarks \
  --install-extension alefragnani.project-manager \
  --install-extension gruntfuggly.todo-tree \
  --install-extension humao.rest-client \
  --install-extension ritwickdey.liveserver \
  --install-extension formulahendry.code-runner \
  --install-extension streetsidesoftware.code-spell-checker \
  --install-extension streetsidesoftware.code-spell-checker-portuguese-brazilian \
  --install-extension ms-vsliveshare.vsliveshare \
  --install-extension vsls-contrib.gistfs \
  --install-extension mongodb.mongodb-vscode \
  --install-extension ms-ossdata.vscode-pgsql \
  --install-extension wakatime.vscode-wakatime \
  --install-extension leonardssh.vscord

Copie o settings.json para o diretorio de configuracao:

# No Windows, o caminho e: %APPDATA%\Code\User\settings.json
# A partir do WSL, voce pode acessar assim:
cp config/vscode/settings.json "/mnt/c/Users/SeuUsuario/AppData/Roaming/Code/User/settings.json"
cp config/vscode/keybindings.json "/mnt/c/Users/SeuUsuario/AppData/Roaming/Code/User/keybindings.json"

Aviso: Substitua SeuUsuario pelo seu nome de usuario do Windows.

7. Ferramentas Essenciais

Todas as ferramentas abaixo devem ser instaladas dentro do WSL2. Para detalhes completos, consulte o Guia de Ferramentas Essenciais.

7.1 mise

curl https://mise.run | sh

Configurar ferramentas:

mkdir -p ~/.config/mise

Crie ~/.config/mise/config.toml:

[tools]
eza = "latest"
node = "lts"

mise install

7.2 eza

# Via mise (ja configurado acima)
mise install eza@latest

# Ou via apt
sudo mkdir -p /etc/apt/keyrings
wget -qO- https://raw.githubusercontent.com/eza-community/eza/main/deb.asc | sudo gpg --dearmor -o /etc/apt/keyrings/gierens.gpg
echo "deb [signed-by=/etc/apt/keyrings/gierens.gpg] http://deb.gierens.de stable main" | sudo tee /etc/apt/sources.list.d/gierens.list
sudo apt update
sudo apt install -y eza

7.3 zoxide

curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

7.4 fzf

sudo apt install -y fzf

7.5 Neovim

sudo add-apt-repository ppa:neovim-ppa/unstable
sudo apt update
sudo apt install -y neovim

7.6 Verificar

eza --version
zoxide --version
fzf --version
nvim --version
mise --version

8. AI no Terminal

Dentro do WSL2, instale as CLIs de IA:

8.1 Claude Code CLI

# Garantir Node.js via mise
mise install node@lts

# Instalar Claude Code
npm install -g @anthropic-ai/claude-code

# Verificar
claude --version

8.2 Gemini CLI

# Instalar Gemini CLI
npm install -g @google/gemini-cli

# Verificar
gemini --version

Dica: Na primeira execucao de cada ferramenta, sera necessario autenticar com sua chave de API respectiva.

9. Git

9.1 Configurar Dentro do WSL2

O Git ja vem instalado no Ubuntu/WSL. Configure-o:

git config --global user.name "seu-usuario"
git config --global user.email "seu-email@exemplo.com"
git config --global init.defaultBranch main
git config --global core.editor nvim
git config --global core.autocrlf input
git config --global pull.rebase true

Ou copie o .gitconfig:

cp config/git/.gitconfig ~/.gitconfig
# Edite com seus dados
git config --global user.name "seu-usuario"
git config --global user.email "seu-email@exemplo.com"

9.2 Chave SSH

# Gerar chave SSH
ssh-keygen -t ed25519 -C "seu-email@exemplo.com"

# Iniciar o agente SSH
eval "$(ssh-agent -s)"

# Adicionar a chave
ssh-add ~/.ssh/id_ed25519

# Copiar chave publica
cat ~/.ssh/id_ed25519.pub

Adicione a chave no GitHub > Settings > SSH Keys.

9.3 Git Credential Manager (Opcional)

Para compartilhar credenciais entre Windows e WSL:

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

Dica: Isso permite que o Git no WSL use o Git Credential Manager do Windows, evitando a necessidade de autenticar separadamente.

10. Fonte Nerd Font

10.1 Instalar no Windows

A fonte deve ser instalada no Windows (nao dentro do WSL), pois o terminal roda no lado do Windows:

Acesse https://www.nerdfonts.com/font-downloads
Baixe JetBrains Mono Nerd Font
Extraia o arquivo ZIP
Selecione todos os arquivos .ttf
Clique com o botao direito e selecione "Instalar para todos os usuarios"

Ou via PowerShell:

# Usando o Oh My Posh (que inclui instalador de fontes)
winget install JanDeDobbeleer.OhMyPosh
oh-my-posh font install JetBrainsMono

10.2 Configurar no Windows Terminal

Abra o Windows Terminal
Acesse Configuracoes (Ctrl + ,)
Selecione seu perfil WSL
Em Aparencia > Fonte, selecione JetBrainsMono Nerd Font
Tamanho: 14
Salve

11. PowerToys (Bonus)

O Microsoft PowerToys e um conjunto de utilitarios que melhoram a produtividade no Windows:

Instalar

winget install Microsoft.PowerToys

Utilitarios Uteis

Utilitario	Descricao
FancyZones	Gerenciamento avancado de janelas com zonas personalizadas
PowerToys Run	Lancador rapido de aplicativos (semelhante ao Spotlight/Alfred)
Color Picker	Seletor de cores em qualquer lugar da tela
File Explorer Add-ons	Preview de arquivos Markdown, SVG, PDF no Explorer
Keyboard Manager	Remapeamento de teclas e atalhos
Always on Top	Fixar janelas sempre no topo (`Win + Ctrl + T`)
Paste as Plain Text	Colar sem formatacao (`Ctrl + Win + V`)

Dica: O PowerToys Run (Alt + Space) e um dos utilitarios mais uteis. Ele permite abrir aplicativos, pesquisar arquivos, fazer calculos e muito mais, tudo sem tirar as maos do teclado.

Checklist Final

Verifique se tudo esta funcionando dentro do WSL2:

# Shell
fish --version
starship --version

# Docker (via Docker Desktop)
docker --version
docker compose version

# Editores
code --version    # Deve funcionar do WSL
nvim --version

# Ferramentas
mise --version
eza --version
zoxide --version
fzf --version

# AI
claude --version
gemini --version

# Git
git --version
ssh -T git@github.com

Voltar ao Inicio | Guia Linux | Ferramentas Essenciais

FilesExpand file tree

windows.md

Latest commit

History

windows.md

File metadata and controls

Guia de Configuracao - Windows (WSL2)

Sumario

1. Pre-requisitos

Requisitos de Sistema

Verificar Versao do Windows

Habilitar Virtualizacao

2. WSL2

2.1 Instalar o WSL2

2.2 Escolher uma Distribuicao

2.3 Configuracao Inicial do WSL2

2.4 Configurar Recursos do WSL2 (Opcional)

3. Windows Terminal

3.1 Instalar

3.2 Configurar Aparencia

3.3 Configuracao via JSON (Opcional)

4. Fish Shell

4.1 Instalar o Fish

4.2 Definir como Shell Padrao

4.3 Instalar o Starship

4.4 Configurar o Fish

5. Docker Desktop

5.1 Instalar o Docker Desktop

5.2 Habilitar Integracao com WSL2

5.3 Verificar no WSL2

6. Visual Studio Code

6.1 Instalar no Windows

6.2 Instalar Extensao WSL

6.3 Abrir Projetos do WSL2

6.4 Importar Configuracoes e Extensoes

7. Ferramentas Essenciais

7.1 mise

7.2 eza

7.3 zoxide

7.4 fzf

7.5 Neovim

7.6 Verificar

8. AI no Terminal

8.1 Claude Code CLI

8.2 Gemini CLI

9. Git

9.1 Configurar Dentro do WSL2

9.2 Chave SSH

9.3 Git Credential Manager (Opcional)

10. Fonte Nerd Font

10.1 Instalar no Windows

10.2 Configurar no Windows Terminal

11. PowerToys (Bonus)

Instalar

Utilitarios Uteis

Checklist Final