Como Instalar Zig com Nix

O Nix é um gerenciador de pacotes funcional que garante builds reprodutíveis e ambientes isolados. Este guia mostra como instalar e usar o Zig com o Nix, seja no NixOS, em outras distribuições Linux, ou no macOS.

Para outros métodos de instalação, consulte o guia completo de instalação. Se busca um método mais simples, veja os guias para Ubuntu, Fedora ou macOS.

Por Que Usar Nix para Instalar o Zig?

O Nix oferece vantagens únicas para o desenvolvimento com Zig:

• Reprodutibilidade — Todos da equipe usam exatamente a mesma versão do Zig
• Isolamento — Diferentes projetos podem usar versões diferentes do Zig sem conflitos
• Rollback — Reverter para uma versão anterior é instantâneo
• Declarativo — A configuração do ambiente é definida em código
• Cross-platform — Funciona no Linux e macOS

Pré-requisito: Instalar o Nix

Em distribuições Linux (não NixOS) ou macOS

Instale o Nix com o instalador oficial:

sh <(curl -L https://nixos.org/nix/install) --daemon

Após a instalação, reinicie o terminal ou execute:

. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

Habilitar Flakes (Recomendado)

Flakes são a forma moderna de usar o Nix. Para habilitar, crie ou edite ~/.config/nix/nix.conf:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Método 1: Instalação Global com nix-env

A forma mais simples de instalar o Zig globalmente no seu sistema:

nix-env -iA nixpkgs.zig

Verificar a Instalação

zig version

Instalar o ZLS junto

nix-env -iA nixpkgs.zls

Listar Versões Disponíveis

nix-env -qaP 'zig*'

Desinstalar

nix-env -e zig

Rollback

Se uma atualização causar problemas, volte à versão anterior:

nix-env --rollback

Método 2: Nix Shell Temporário

Use o nix-shell para criar um ambiente temporário com o Zig, sem instalar nada permanentemente:

nix-shell -p zig

Dentro do shell, o Zig estará disponível:

zig version
zig run meu-programa.zig

Ao sair do shell (exit ou Ctrl+D), o Zig não estará mais disponível no PATH.

Com o novo comando nix (flakes habilitado):

nix shell nixpkgs#zig

Isso é útil para testar rapidamente o Zig ou para rodar um script que precisa dele sem poluir seu sistema.

Método 3: Flakes — Ambiente por Projeto (Recomendado)

Flakes são a forma mais poderosa de gerenciar dependências com Nix. Cada projeto tem seu próprio flake.nix que define exatamente o ambiente necessário.

Criar um Projeto com Flake

Crie o arquivo flake.nix na raiz do seu projeto:

{
  description = "Meu projeto Zig";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in
      {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            zig
            zls
          ];

          shellHook = ''
            echo "Ambiente Zig ativado!"
            echo "Zig: $(zig version)"
            echo "ZLS: $(zls --version)"
          '';
        };
      }
    );
}

Usar o Ambiente

# Entrar no ambiente de desenvolvimento
nix develop

# Ou executar um comando diretamente
nix develop --command zig build

Fixar uma Versão Específica

Para garantir que todos usem exatamente a mesma versão, fixe o input do nixpkgs a um commit específico:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/a3c0b3b21515f74fd2665903d4ce6bc4dc81e3de";
};

Para encontrar o commit que contém uma versão específica do Zig:

# Pesquisar versões do Zig no nixpkgs
nix search nixpkgs zig

Método 4: Zig Overlay para Versões Específicas

A comunidade mantém um overlay Nix que oferece todas as versões do Zig, incluindo nightlies. Este é o método ideal quando você precisa de uma versão específica.

Configurar o flake.nix com o Zig Overlay

{
  description = "Projeto Zig com versão específica";

  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 = [
            # Usar uma versão específica do Zig
            zigpkg."0.14.0"

            # Ou usar a versão master/nightly:
            # zigpkg.master

            pkgs.zls
          ];

          shellHook = ''
            echo "Zig $(zig version) pronto para uso!"
          '';
        };
      }
    );
}

Listar Versões Disponíveis no Overlay

nix flake show github:mitchellh/zig-overlay

NixOS: Instalação no Sistema

Se você usa NixOS como seu sistema operacional, pode adicionar o Zig à configuração do sistema.

Instalação via configuration.nix

Edite /etc/nixos/configuration.nix:

{ config, pkgs, ... }:

{
  # Instalar Zig globalmente no sistema
  environment.systemPackages = with pkgs; [
    zig
    zls
  ];
}

Aplique a configuração:

sudo nixos-rebuild switch

Instalação via Home Manager

Se usa o Home Manager para gerenciar seu ambiente:

{ config, pkgs, ... }:

{
  home.packages = with pkgs; [
    zig
    zls
  ];
}

Aplique:

home-manager switch

Integração com direnv

O direnv ativa automaticamente o ambiente Nix quando você entra no diretório do projeto. Isso elimina a necessidade de executar nix develop manualmente.

Configurar direnv

1. Instale o direnv:

nix-env -iA nixpkgs.direnv nixpkgs.nix-direnv

2. Adicione ao seu shell (.bashrc ou .zshrc):

eval "$(direnv hook bash)"  # Para Bash
eval "$(direnv hook zsh)"   # Para Zsh

3. Crie um arquivo .envrc na raiz do projeto:

echo "use flake" > .envrc
direnv allow

Agora, ao entrar no diretório do projeto, o direnv ativará automaticamente o ambiente com Zig e ZLS. Ao sair, o ambiente será desativado.

Exemplo Completo com direnv

Estrutura do projeto:

meu-projeto-zig/
├── .envrc          # use flake
├── flake.nix       # Definição do ambiente
├── flake.lock      # Versões fixadas (gerado automaticamente)
├── build.zig
├── build.zig.zon
└── src/
    └── main.zig

Cache Binário

Para acelerar a instalação, configure caches binários para evitar compilações locais:

# Em flake.nix, adicione substituters
nixConfig = {
  extra-substituters = [
    "https://cache.nixos.org"
    "https://nix-community.cachix.org"
  ];
  extra-trusted-public-keys = [
    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
  ];
};

Problemas Comuns

“error: experimental Nix feature ‘flakes’ is disabled”

Habilite flakes conforme descrito na seção de pré-requisitos:

echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Conflito de versões

Se você tem o Zig instalado via nix-env e via flake, o nix-env tem prioridade. Remova a instalação global se usar flakes:

nix-env -e zig

Build demora muito

Use caches binários para evitar compilações locais. O nixpkgs oficial já fornece binários pré-compilados para a maioria dos pacotes.

Para mais soluções, visite nossa página de erros comuns.

Próximos Passos

Com o Zig instalado via Nix:

1. Configure seu editor — VS Code ou Neovim
2. Crie seu primeiro projeto — Primeiro projeto Zig
3. Aprenda a linguagem — Introdução ao Zig
4. Configure CI/CD — GitHub Actions com Zig
5. Veja exemplos — Receitas

Se também trabalha com Docker, confira como usar Zig com Docker para criar imagens de produção otimizadas.