---
title: "Como Gerenciar Múltiplas Versões do Zig"
url: "https://ziglang.com.br/instalacao/como-gerenciar-m%C3%BAltiplas-vers%C3%B5es-do-zig/"
markdown_url: "https://ziglang.com.br/instalacao/como-gerenciar-m%C3%BAltiplas-vers%C3%B5es-do-zig.MD"
description: "Aprenda a gerenciar múltiplas versões do Zig com zigup, links simbólicos e Nix. Boas práticas para alternar entre versões em projetos diferentes."
date: "2026-02-21"
author: "Zig Brasil"
---

# Como Gerenciar Múltiplas Versões do Zig

Aprenda a gerenciar múltiplas versões do Zig com zigup, links simbólicos e Nix. Boas práticas para alternar entre versões em projetos diferentes.


# Como Gerenciar Múltiplas Versões do Zig

Conforme você trabalha com o Zig em diferentes projetos, inevitavelmente surge a necessidade de manter **múltiplas versões** do compilador no mesmo sistema. Um projeto legado pode depender do Zig 0.13.0, enquanto outro exige a versão estável mais recente, e talvez você ainda queira testar funcionalidades experimentais da versão nightly. Este guia apresenta as ferramentas e técnicas para gerenciar essas versões de forma organizada e eficiente.

Se você ainda não instalou o Zig pela primeira vez, comece pelo [guia completo de instalação](/instalacao/) e escolha a plataforma adequada: [Ubuntu](/instalacao/instalar-zig-linux-ubuntu/), [Fedora](/instalacao/instalar-zig-linux-fedora/), [Arch Linux](/instalacao/instalar-zig-linux-arch/), [macOS](/instalacao/instalar-zig-macos/) ou [Windows](/instalacao/instalar-zig-windows/).

---

## Por Que Gerenciar Múltiplas Versões?

Existem diversos cenários em que manter mais de uma versão do Zig instalada é essencial:

- **Compatibilidade de projetos** — Projetos diferentes podem exigir versões diferentes do compilador. O `build.zig` e as APIs da biblioteca padrão mudam entre versões, e código escrito para uma versão pode não compilar em outra.
- **Testar versões nightly** — A versão de desenvolvimento (master/nightly) do Zig traz as funcionalidades mais recentes, mas pode conter mudanças que quebram compatibilidade. Ter acesso a ela sem afetar seu ambiente estável é fundamental.
- **Contribuir com o ecossistema** — Se você mantém bibliotecas ou contribui para projetos open-source, precisa testar contra múltiplas versões para garantir compatibilidade.
- **Migração gradual** — Ao atualizar um projeto grande para uma nova versão do Zig, é útil manter a versão antiga disponível para comparação e rollback.

---

## Método 1: zigup (Recomendado)

O **zigup** é um gerenciador de versões dedicado ao Zig, similar ao `rustup` para Rust ou ao `nvm` para Node.js. Ele simplifica o download, a instalação e a alternância entre versões.

### Instalar o zigup

No **Linux** e **macOS**, baixe o binário pré-compilado:

```bash
# Linux x86_64
curl -LO https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-linux.tar.xz
tar -xf zigup-x86_64-linux.tar.xz
sudo mv zigup /usr/local/bin/

# macOS (Apple Silicon)
curl -LO https://github.com/marler8997/zigup/releases/latest/download/zigup-aarch64-macos.tar.xz
tar -xf zigup-aarch64-macos.tar.xz
sudo mv zigup /usr/local/bin/

# macOS (Intel)
curl -LO https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-macos.tar.xz
tar -xf zigup-x86_64-macos.tar.xz
sudo mv zigup /usr/local/bin/
```

No **Windows**, baixe o executável da [página de releases do zigup](https://github.com/marler8997/zigup/releases) e adicione o diretório ao PATH.

Verifique a instalação:

```bash
zigup --help
```

### Instalar Versões do Zig com zigup

```bash
# Instalar a versão estável mais recente
zigup 0.14.0

# Instalar uma versão específica mais antiga
zigup 0.13.0

# Instalar a versão nightly (master)
zigup master
```

O zigup baixa o compilador e o configura automaticamente no PATH. Cada versão é armazenada em um diretório separado, sem sobrescrever as outras.

### Alternar Entre Versões

```bash
# Mudar para a versão 0.13.0
zigup default 0.13.0

# Mudar para a versão 0.14.0
zigup default 0.14.0

# Mudar para a nightly
zigup default master
```

Após trocar, confirme:

```bash
zig version
```

### Listar Versões Instaladas

```bash
zigup list
```

Saída esperada:

```
0.13.0
0.14.0 (default)
master
```

### Remover uma Versão

```bash
zigup remove 0.13.0
```

### Atualizar a Versão Nightly

A versão master é atualizada com frequência. Para obter a compilação mais recente:

```bash
zigup master
```

O zigup detecta automaticamente se já existe uma versão master instalada e a substitui pela nova.

---

## Método 2: Gerenciamento Manual com Links Simbólicos

Se você prefere não instalar ferramentas adicionais, é possível gerenciar versões manualmente usando diretórios separados e links simbólicos. Esse método funciona em qualquer sistema Linux ou macOS.

### Estrutura de Diretórios

Crie um diretório base para armazenar todas as versões:

```bash
sudo mkdir -p /opt/zig-versions
```

Baixe e extraia cada versão em seu próprio subdiretório:

```bash
# Versão 0.14.0
curl -LO https://ziglang.org/download/0.14.0/zig-linux-x86_64-0.14.0.tar.xz
tar -xf zig-linux-x86_64-0.14.0.tar.xz
sudo mv zig-linux-x86_64-0.14.0 /opt/zig-versions/0.14.0

# Versão 0.13.0
curl -LO https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
tar -xf zig-linux-x86_64-0.13.0.tar.xz
sudo mv zig-linux-x86_64-0.13.0 /opt/zig-versions/0.13.0
```

### Criar o Link Simbólico

Use um link simbólico em `/usr/local/bin` para apontar para a versão ativa:

```bash
sudo ln -sf /opt/zig-versions/0.14.0/zig /usr/local/bin/zig
```

Para alternar para outra versão, basta atualizar o link:

```bash
sudo ln -sf /opt/zig-versions/0.13.0/zig /usr/local/bin/zig
```

Verifique:

```bash
zig version
```

### Script de Alternância

Para facilitar a troca, crie um script `zigswitch`:

```bash
#!/bin/bash
set -euo pipefail

ZIG_BASE="/opt/zig-versions"
ZIG_LINK="/usr/local/bin/zig"

if [ $# -eq 0 ]; then
    echo "Versões disponíveis:"
    for dir in "$ZIG_BASE"/*/; do
        version=$(basename "$dir")
        current=""
        if [ "$(readlink -f "$ZIG_LINK")" = "$ZIG_BASE/$version/zig" ]; then
            current=" (ativa)"
        fi
        echo "  $version$current"
    done
    echo ""
    echo "Uso: zigswitch <versão>"
    exit 0
fi

VERSION="$1"

if [ ! -d "$ZIG_BASE/$VERSION" ]; then
    echo "Erro: versão $VERSION não encontrada em $ZIG_BASE"
    echo "Versões disponíveis:"
    ls "$ZIG_BASE"
    exit 1
fi

sudo ln -sf "$ZIG_BASE/$VERSION/zig" "$ZIG_LINK"
echo "Zig alterado para versão $VERSION"
zig version
```

Salve como `/usr/local/bin/zigswitch`, torne executável e use:

```bash
sudo chmod +x /usr/local/bin/zigswitch

# Listar versões disponíveis
zigswitch

# Alternar para uma versão específica
zigswitch 0.14.0
```

---

## Método 3: Nix com Ambientes por Projeto

O gerenciador de pacotes **Nix** oferece uma abordagem declarativa para fixar a versão do Zig por projeto, usando flakes e devshells. Cada projeto pode ter seu próprio `flake.nix` especificando a versão exata do compilador.

Para um guia completo desse método, consulte a página [Instalar Zig com Nix](/instalacao/instalar-zig-nix/), que cobre flakes, o zig-overlay e a integração com direnv para ativação automática do ambiente.

### Exemplo Rápido com Zig Overlay

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    zig-overlay.url = "github:mitchellh/zig-overlay";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, zig-overlay, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
        zigpkg = zig-overlay.packages.${system};
      in {
        devShells.default = pkgs.mkShell {
          buildInputs = [
            zigpkg."0.13.0"   # Fixar versão específica
            pkgs.zls
          ];
        };
      }
    );
}
```

Entre no ambiente com `nix develop` e o Zig 0.13.0 estará disponível automaticamente, sem afetar a instalação global.

---

## Método 4: Docker para Isolamento Total

Outra alternativa é usar containers Docker com versões específicas do Zig. Esse método garante isolamento completo e é especialmente útil em ambientes de CI/CD.

Consulte o guia [Usar Zig com Docker](/instalacao/instalar-zig-docker/) para instruções detalhadas sobre como criar imagens com versões específicas do compilador.

Exemplo rápido:

```bash
# Executar com Zig 0.14.0
docker run --rm -v $(pwd):/app -w /app minha-imagem-zig:0.14.0 zig build

# Executar com Zig 0.13.0
docker run --rm -v $(pwd):/app -w /app minha-imagem-zig:0.13.0 zig build
```

---

## Boas Práticas para Gerenciamento de Versões

### Documentar a versão exigida pelo projeto

Adicione a versão mínima e máxima suportada do Zig na documentação do projeto. O arquivo `build.zig.zon` é o local adequado para indicar a versão mínima:

```zig
.{
    .name = "meu-projeto",
    .version = "1.0.0",
    .minimum_zig_version = "0.14.0",
    .dependencies = .{},
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}
```

### Verificar a versão no build.zig

Adicione uma verificação automática no início do `build.zig` para alertar sobre incompatibilidades:

```zig
const std = @import("std");
const builtin = @import("builtin");

pub fn build(b: *std.Build) void {
    // Verificar versão mínima do Zig
    const min_version = std.SemanticVersion.parse("0.14.0") catch unreachable;
    if (builtin.zig_version.order(min_version) == .lt) {
        @compileError("Este projeto requer Zig >= 0.14.0. Versão atual: " ++ builtin.zig_version_string);
    }

    // ... resto do build
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "meu-projeto",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    b.installArtifact(exe);
}
```

### Manter o ZLS compatível

O **ZLS** (Zig Language Server) precisa ser compatível com a versão do Zig que você está usando. Ao trocar de versão do Zig, certifique-se de usar a versão correspondente do ZLS. Consulte os guias de configuração do [VS Code](/instalacao/configurar-vscode-zig/) ou do [Neovim](/instalacao/configurar-neovim-zig/) para saber como configurar o ZLS por projeto.

### Testar contra múltiplas versões no CI

Se você mantém uma biblioteca Zig, configure o CI para testar contra todas as versões que deseja suportar. Consulte nosso guia de [Zig no GitHub Actions](/instalacao/zig-ci-github-actions/) para ver como criar uma matrix de versões no pipeline.

---

## Comparação dos Métodos

| Método | Facilidade | Isolamento | Automatização | Ideal para |
|---|---|---|---|---|
| zigup | Alta | Médio | Alta | Desenvolvedores individuais |
| Manual (links simbólicos) | Média | Médio | Baixa | Quem prefere controle total |
| Nix (flakes) | Média | Alto | Alta | Equipes, reprodutibilidade |
| Docker | Média | Muito alto | Alta | CI/CD, ambientes descartáveis |

---

## Problemas Comuns

### "zig version" mostra versão errada após troca

Isso pode acontecer se houver múltiplas entradas do Zig no PATH. Verifique qual binário está sendo executado:

```bash
which zig
```

Se o caminho não for o esperado, revise a ordem das entradas no PATH do seu `~/.bashrc` ou `~/.zshrc`.

### zigup não encontra a versão solicitada

Verifique se a versão existe na [página oficial de downloads](https://ziglang.org/download/). Versões muito antigas podem ter sido removidas dos servidores de distribuição.

### Conflito entre instalação do sistema e zigup

Se você instalou o Zig via gerenciador de pacotes do sistema (`apt`, `brew`, `pacman`), ele pode ter prioridade sobre o zigup no PATH. Remova a instalação do sistema ou ajuste a ordem do PATH para priorizar o zigup.

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

---

## Próximos Passos

Com o gerenciamento de versões configurado:

1. **Compile o Zig do fonte** — Se quiser a versão mais recente possível, veja como [compilar o Zig do código-fonte](/instalacao/zig-compilar-do-fonte/)
2. **Configure CI/CD** — Teste múltiplas versões com [GitHub Actions](/instalacao/zig-ci-github-actions/)
3. **Crie seu primeiro projeto** — [Primeiro projeto Zig](/instalacao/zig-primeiro-projeto/)
4. **Configure seu editor** — [VS Code](/instalacao/configurar-vscode-zig/) ou [Neovim](/instalacao/configurar-neovim-zig/)
5. **Aprenda a linguagem** — [Introdução ao Zig](/tutoriais/introducao-ao-zig/)
6. **Veja exemplos práticos** — [Receitas](/receitas/)