--- title: "zigup — Gerenciador de Versões do Zig: Instalação e Uso" url: "https://ziglang.com.br/ecossistema/zigup-gerenciador-de-vers%C3%B5es-do-zig-instala%C3%A7%C3%A3o-e-uso/" markdown_url: "https://ziglang.com.br/ecossistema/zigup-gerenciador-de-vers%C3%B5es-do-zig-instala%C3%A7%C3%A3o-e-uso.MD" description: "Guia completo do zigup, o gerenciador de versões do Zig: instale, alterne e gerencie múltiplas versões do compilador Zig facilmente." date: "2026-02-21" author: "Zig Brasil" --- # zigup — Gerenciador de Versões do Zig: Instalação e Uso Guia completo do zigup, o gerenciador de versões do Zig: instale, alterne e gerencie múltiplas versões do compilador Zig facilmente. # zigup — Gerenciador de Versões do Zig: Instalação e Uso Trabalhar com Zig frequentemente exige lidar com múltiplas versões do compilador. Projetos diferentes podem depender de versões específicas, você pode querer testar o nightly build mais recente sem comprometer seu ambiente estável, ou precisa manter compatibilidade com versões anteriores. O zigup resolve todos esses problemas de forma elegante, funcionando como o nvm do Node.js ou o rustup do Rust, mas para o ecossistema Zig. ## O Que É o zigup O zigup é um gerenciador de versões do compilador Zig que permite instalar, remover e alternar entre diferentes versões com comandos simples. Escrito em Zig, ele é rápido, leve e não possui dependências externas. O zigup baixa binários oficiais diretamente dos servidores de distribuição do Zig, garantindo integridade e autenticidade. ## Instalação do zigup ### Download Direto A forma mais simples é baixar o binário pré-compilado: ```bash # Linux x86_64 curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-linux.tar.xz | tar -xJ sudo mv zigup /usr/local/bin/ # macOS x86_64 curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-macos.tar.xz | tar -xJ sudo mv zigup /usr/local/bin/ # macOS ARM64 (Apple Silicon) curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-aarch64-macos.tar.xz | tar -xJ sudo mv zigup /usr/local/bin/ # Windows (PowerShell) Invoke-WebRequest -Uri "https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-windows.zip" -OutFile zigup.zip Expand-Archive zigup.zip ``` ### Compilação a Partir do Fonte Se você já tem uma versão do Zig instalada: ```bash git clone https://github.com/marler8997/zigup cd zigup zig build -Doptimize=ReleaseSafe sudo cp zig-out/bin/zigup /usr/local/bin/ ``` ### Via Gerenciadores de Pacotes ```bash # Homebrew (macOS e Linux) brew install zigup # Nix nix-env -iA nixpkgs.zigup ``` ## Configuração Inicial Após instalar o zigup, configure o diretório onde as versões do Zig serão armazenadas: ```bash # O zigup usa ~/.local/share/zigup por padrão no Linux # e ~/Library/zigup no macOS # Verifique a configuração zigup --help ``` Certifique-se de que o diretório de binários do zigup está no seu PATH. Adicione ao seu `.bashrc`, `.zshrc` ou equivalente: ```bash export PATH="$HOME/.local/share/zigup:$PATH" ``` ## Comandos Essenciais ### Instalar uma Versão ```bash # Instalar versão específica zigup install 0.13.0 # Instalar o nightly mais recente zigup install master # Instalar e definir como padrão zigup default 0.13.0 ``` ### Listar Versões Instaladas ```bash zigup list # Saída: # 0.12.0 # 0.13.0 # 0.14.0-dev.1234+abcdef # master (default) ``` ### Alternar Entre Versões ```bash # Definir versão padrão zigup default 0.13.0 # Verificar versão ativa zig version # 0.13.0 ``` ### Remover uma Versão ```bash zigup remove 0.12.0 ``` ### Atualizar o Nightly ```bash # Baixar a build master mais recente zigup install master # Isso substitui a versão master anterior ``` ## Fluxo de Trabalho com Múltiplos Projetos Um cenário comum é ter projetos que dependem de versões diferentes do Zig. O zigup facilita essa gestão: ```bash # Projeto A usa Zig 0.13.0 cd ~/projetos/projeto-a zigup default 0.13.0 zig build # Projeto B usa a versão de desenvolvimento cd ~/projetos/projeto-b zigup default master zig build # Voltar para o projeto A cd ~/projetos/projeto-a zigup default 0.13.0 ``` ### Dica: Scripts de Projeto Crie um script `setup.sh` na raiz de cada projeto para automatizar a seleção de versão: ```bash #!/bin/bash # setup.sh REQUIRED_ZIG="0.13.0" zigup default $REQUIRED_ZIG echo "Zig $REQUIRED_ZIG ativado para este projeto" ``` ## Integração com ZLS O [ZLS (Zig Language Server)](/ecossistema/zls-language-server/) precisa corresponder à versão do compilador Zig em uso. O zigup pode gerenciar o ZLS em conjunto: ```bash # Instalar ZLS correspondente à versão do Zig zigup fetch-zls 0.13.0 # O ZLS será automaticamente selecionado junto com a versão do Zig zigup default 0.13.0 # Agora tanto zig quanto zls apontam para a versão 0.13.0 ``` Essa integração é essencial para garantir que o autocompletar e os diagnósticos do editor estejam sincronizados com o compilador. ## Integração com CI/CD O zigup é útil em pipelines de CI/CD para garantir versões reproduzíveis: ```yaml # GitHub Actions - name: Instalar zigup run: | curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-linux.tar.xz | tar -xJ sudo mv zigup /usr/local/bin/ - name: Instalar Zig run: | zigup install 0.13.0 zigup default 0.13.0 - name: Build run: zig build - name: Testes run: zig build test ``` ```yaml # GitLab CI build: script: - curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-linux.tar.xz | tar -xJ - mv zigup /usr/local/bin/ - zigup install 0.13.0 - zigup default 0.13.0 - zig build - zig build test ``` ## Comparação com Alternativas ### Download Manual Sem o zigup, gerenciar versões requer download manual, extração e manipulação de PATH. Isso é tedioso e propenso a erros, especialmente quando se precisa alternar frequentemente. ### Docker Usar containers Docker com diferentes versões do Zig é uma alternativa, mas adiciona overhead e complexidade. O zigup é mais leve e rápido para desenvolvimento local. ### asdf O gerenciador de versões genérico asdf tem um plugin para Zig, mas o zigup oferece melhor integração com o ecossistema (como o gerenciamento conjunto do ZLS) e é mantido por membros ativos da comunidade Zig. ## Resolução de Problemas ### Versão Não Encontrada Se o zigup não encontra uma versão, verifique se ela existe nos releases oficiais. Versões de desenvolvimento seguem o formato `0.14.0-dev.NNNN+hash`. ### Conflito de PATH Se `zig version` mostra uma versão diferente da esperada, verifique se não há outra instalação do Zig no PATH com prioridade maior: ```bash which -a zig # Deve mostrar apenas o caminho gerenciado pelo zigup ``` ### Permissões Em Linux, o zigup armazena binários em `~/.local/share/zigup/`. Certifique-se de que esse diretório tem permissões corretas: ```bash chmod -R u+rwx ~/.local/share/zigup/ ``` ## Boas Práticas 1. **Documente a versão do Zig** necessária no README de cada projeto 2. **Use versões estáveis** para projetos em produção; reserve o master para experimentação 3. **Atualize o ZLS** sempre que mudar a versão do compilador 4. **Automatize no CI** usando zigup para garantir reprodutibilidade 5. **Limpe versões antigas** periodicamente com `zigup remove` para economizar espaço em disco ## Próximos Passos Com o zigup configurado, explore o [sistema de build](/ecossistema/zig-build-system-overview/) e o [gerenciador de pacotes](/ecossistema/zig-pkg-manager/) para montar seu ambiente de desenvolvimento completo. Consulte nossos [tutoriais](/tutoriais/) para projetos práticos e a seção de [carreira](/carreira/) para oportunidades profissionais com Zig.