---
title: "Como Instalar Zig no WSL — Windows Subsystem for Linux"
url: "https://ziglang.com.br/instalacao/como-instalar-zig-no-wsl-windows-subsystem-for-linux/"
markdown_url: "https://ziglang.com.br/instalacao/como-instalar-zig-no-wsl-windows-subsystem-for-linux.MD"
description: "Guia completo para instalar e configurar o Zig no WSL (Windows Subsystem for Linux). WSL2, Ubuntu, integração com VS Code e dicas."
date: "2026-02-21"
author: "Zig Brasil"
---

# Como Instalar Zig no WSL — Windows Subsystem for Linux

Guia completo para instalar e configurar o Zig no WSL (Windows Subsystem for Linux). WSL2, Ubuntu, integração com VS Code e dicas.


# 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](/instalacao/instalar-zig-windows/). Para uma visão geral de todas as opções, consulte o [guia completo de instalação](/instalacao/).

---

## 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:

```powershell
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:

```powershell
wsl --list --online
```

Para instalar uma distribuição específica:

```powershell
# 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

```powershell
wsl --version
```

Certifique-se de estar usando WSL2 para melhor performance:

```powershell
wsl --set-default-version 2
```

### Configuração Inicial

Na primeira execução do WSL, crie seu usuário e senha:

```bash
# O WSL vai solicitar:
# Enter new UNIX username: seunome
# New password: ********
```

Depois, atualize o sistema:

```bash
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)

```bash
# 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

```bash
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

```zig
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;
        }
    }
}
```

```bash
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

1. Instale o [VS Code no Windows](https://code.visualstudio.com/)
2. Instale a extensão **WSL** (identificador: `ms-vscode-remote.remote-wsl`)

### Abrir um Projeto no WSL

De dentro do terminal WSL:

```bash
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:

```bash
# 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:

```json
{
    "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](/instalacao/configurar-vscode-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`):

```ini
[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:

```bash
# 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:

```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)

```bash
zig build
```

### Compilar para Windows (cross-compilation)

```bash
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:

```bash
#!/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:

```bash
# 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:

```bash
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):

```bash
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`:

```ini
[boot]
systemd=true
```

Reinicie o WSL:

```powershell
wsl --shutdown
```

---

## Problemas Comuns no WSL

### WSL não inicia

```powershell
# 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`:

```ini
[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:

```bash
# Verificar portas em uso
ss -tlnp
```

Para mais soluções, visite nossa página de [erros comuns](/erros/).

---

## Próximos Passos

Com o Zig instalado no WSL:

1. **Configure o VS Code** — [Guia completo do VS Code para Zig](/instalacao/configurar-vscode-zig/) com suporte a WSL
2. **Crie seu primeiro projeto** — [Primeiro projeto Zig](/instalacao/zig-primeiro-projeto/)
3. **Aprenda a linguagem** — [Introdução ao Zig](/tutoriais/introducao-ao-zig/)
4. **Gerencie versões** — [Gerenciar versões do Zig](/instalacao/zig-gerenciar-versoes/)
5. **Veja exemplos** — [Receitas](/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](/instalacao/instalar-zig-docker/).