Como Instalar Zig no WSL (Windows Subsystem for Linux)
O WSL (Windows Subsystem for Linux) permite rodar um ambiente Linux completo dentro do Windows. Esta é uma excelente opção para desenvolvedores que querem usar o Zig em um ambiente Linux sem abandonar o Windows. Este guia cobre a instalação do WSL, do Zig dentro do WSL, e a integração com editores do Windows.
Se você prefere instalar o Zig diretamente no Windows, veja o guia de instalação no Windows. Para uma visão geral de todas as opções, consulte o guia completo de instalação.
Por Que Usar o WSL para Zig?
O WSL é especialmente vantajoso para desenvolvimento com Zig por vários motivos:
- Ambiente Linux nativo — Muitas ferramentas e bibliotecas de desenvolvimento funcionam melhor no Linux
- Cross-compilation facilitada — Compile para Linux nativamente e para Windows com cross-compilation
- Ferramentas Unix — Acesso a
make,cmake, shell scripts e toda a stack Unix - Integração com VS Code — O VS Code conecta diretamente ao WSL com suporte completo
- Performance — O WSL2 oferece performance quase nativa para operações de I/O
Passo 1: Instalar o WSL
Instalação Rápida (Windows 10 versão 2004+ e Windows 11)
Abra o PowerShell como Administrador e execute:
wsl --install
Isso instala o WSL2 com Ubuntu como distribuição padrão. Reinicie o computador quando solicitado.
Instalação com Distribuição Específica
Para ver as distribuições disponíveis:
wsl --list --online
Para instalar uma distribuição específica:
# Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04
# Debian
wsl --install -d Debian
# Fedora (via Microsoft Store)
Verificar a Versão do WSL
wsl --version
Certifique-se de estar usando WSL2 para melhor performance:
wsl --set-default-version 2
Configuração Inicial
Na primeira execução do WSL, crie seu usuário e senha:
# O WSL vai solicitar:
# Enter new UNIX username: seunome
# New password: ********
Depois, atualize o sistema:
sudo apt update && sudo apt upgrade -y
Passo 2: Instalar o Zig no WSL
Dentro do terminal WSL, a instalação é idêntica ao Linux. Recomendamos o download direto para ter a versão mais recente.
Download Direto (Recomendado)
# Verificar a arquitetura
uname -m
# Baixar o Zig
ZIG_VERSION="0.14.0"
curl -LO "https://ziglang.org/download/${ZIG_VERSION}/zig-linux-x86_64-${ZIG_VERSION}.tar.xz"
# Extrair
tar -xf "zig-linux-x86_64-${ZIG_VERSION}.tar.xz"
# Instalar
sudo mv "zig-linux-x86_64-${ZIG_VERSION}" /opt/zig
# Adicionar ao PATH
echo 'export PATH="/opt/zig:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Verificar
zig version
Via Snap
sudo apt install snapd
sudo snap install zig --classic --beta
Nota: O Snap pode ter limitações no WSL em algumas configurações. Se encontrar problemas, use o download direto.
Teste Rápido
const std = @import("std");
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try stdout.print("Zig no WSL está funcionando!\n", .{});
// Demonstrar acesso ao sistema de arquivos
var dir = try std.fs.cwd().openDir(".", .{ .iterate = true });
defer dir.close();
try stdout.print("Arquivos no diretório atual:\n", .{});
var iter = dir.iterate();
var count: u32 = 0;
while (try iter.next()) |entry| {
if (count < 5) {
try stdout.print(" - {s}\n", .{entry.name});
count += 1;
}
}
}
zig run teste.zig
Passo 3: Integração WSL com VS Code
O VS Code é o editor mais popular para desenvolvimento no WSL, graças à extensão Remote - WSL.
Instalar a Extensão Remote - WSL
- Instale o VS Code no Windows
- Instale a extensão WSL (identificador:
ms-vscode-remote.remote-wsl)
Abrir um Projeto no WSL
De dentro do terminal WSL:
cd ~/meu-projeto-zig
code .
Isso abre o VS Code no Windows conectado ao WSL. Todos os terminais integrados do VS Code executarão no ambiente Linux.
Configurar o ZLS no WSL
Instale o ZLS dentro do WSL:
# Baixar o ZLS
ZLS_VERSION="0.14.0"
curl -LO "https://github.com/zigtools/zls/releases/download/${ZLS_VERSION}/zls-x86_64-linux.tar.xz"
tar -xf "zls-x86_64-linux.tar.xz"
sudo mv zls /usr/local/bin/
No VS Code (conectado ao WSL), instale a extensão Zig Language e configure o caminho do ZLS nas configurações:
{
"zig.zls.path": "/usr/local/bin/zls",
"zig.path": "/opt/zig/zig"
}
Para instruções mais detalhadas, veja o guia de configuração do VS Code para Zig.
Passo 4: Configuração de Performance no WSL
Arquivo de Configuração do WSL
Crie o arquivo .wslconfig no diretório do usuário Windows (C:\Users\SeuNome\.wslconfig):
[wsl2]
memory=8GB
processors=4
swap=4GB
[experimental]
sparseVhd=true
Ajuste os valores de memória e processadores de acordo com seu hardware.
Localização dos Arquivos
Para melhor performance, mantenha seus projetos Zig dentro do sistema de arquivos do WSL, não no diretório Windows montado:
# BOM - Sistema de arquivos do WSL (rápido)
~/projetos/meu-app-zig/
# EVITAR - Sistema de arquivos do Windows montado (lento)
/mnt/c/Users/SeuNome/projetos/meu-app-zig/
A diferença de performance de I/O entre o sistema de arquivos nativo do WSL e o montado do Windows pode ser de 10x ou mais, o que afeta diretamente a velocidade de compilação do Zig.
Acessar Arquivos do WSL no Windows
Você pode acessar os arquivos do WSL no Explorer do Windows:
\\wsl$\Ubuntu\home\seunome\projetos
Ou pelo PowerShell:
explorer.exe \\wsl$\Ubuntu\home\$env:USERNAME
Passo 5: Cross-Compilation no WSL
Uma das grandes vantagens de usar o WSL é poder compilar tanto para Linux quanto para Windows:
Compilar para Linux (nativo no WSL)
zig build
Compilar para Windows (cross-compilation)
zig build-exe --target=x86_64-windows-gnu src/main.zig -femit-bin=app.exe
Compilar para Ambas as Plataformas
Crie um script para compilar para múltiplos alvos:
#!/bin/bash
set -euo pipefail
echo "=== Compilando para Linux ==="
zig build -Doptimize=.ReleaseSafe
cp zig-out/bin/meu-app ./meu-app-linux
echo "=== Compilando para Windows ==="
zig build-exe --target=x86_64-windows-gnu -Doptimize=.ReleaseSafe src/main.zig -femit-bin=meu-app.exe
echo "=== Pronto! ==="
ls -la meu-app-linux meu-app.exe
Executar o Binário Windows do WSL
O WSL2 pode executar programas Windows diretamente:
# Compilar para Windows
zig build-exe --target=x86_64-windows-gnu main.zig -femit-bin=app.exe
# Executar o .exe diretamente do WSL
./app.exe
Configurações Extras para o WSL
Git no WSL
Configure o Git dentro do WSL:
git config --global user.name "Seu Nome"
git config --global user.email "seu@email.com"
git config --global core.autocrlf input
A configuração core.autocrlf input é importante para evitar problemas com finais de linha entre Windows e Linux.
Configurar SSH
Para usar Git com SSH (GitHub, GitLab):
ssh-keygen -t ed25519 -C "seu@email.com"
cat ~/.ssh/id_ed25519.pub
Copie a chave pública e adicione ao GitHub/GitLab.
Systemd no WSL
O WSL2 suporta systemd, o que pode ser útil para alguns cenários. Para habilitar, crie /etc/wsl.conf:
[boot]
systemd=true
Reinicie o WSL:
wsl --shutdown
Problemas Comuns no WSL
WSL não inicia
# Reiniciar o WSL
wsl --shutdown
wsl
Erro “Cannot access /mnt/c”
Verifique se o WSL tem permissão para montar drives do Windows. Edite /etc/wsl.conf:
[automount]
enabled=true
root=/mnt/
options="metadata,umask=22,fmask=11"
Compilação lenta
Certifique-se de que seus arquivos estão no sistema de arquivos nativo do WSL, não em /mnt/c/. Verifique também os limites de memória no .wslconfig.
Porta em uso ao rodar servidor
Se um servidor Zig não consegue abrir uma porta, verifique se não há conflito com serviços do Windows:
# Verificar portas em uso
ss -tlnp
Para mais soluções, visite nossa página de erros comuns.
Próximos Passos
Com o Zig instalado no WSL:
- Configure o VS Code — Guia completo do VS Code para Zig com suporte a WSL
- Crie seu primeiro projeto — Primeiro projeto Zig
- Aprenda a linguagem — Introdução ao Zig
- Gerencie versões — Gerenciar versões do Zig
- Veja exemplos — Receitas
Se precisar de um ambiente Docker dentro do WSL, o Docker Desktop integra nativamente com o WSL2. Confira nosso guia de Zig com Docker.