---
title: "Como Instalar Zig com Nix — NixOS, Flakes e Ambientes Reprodutíveis"
url: "https://ziglang.com.br/instalacao/como-instalar-zig-com-nix-nixos-flakes-e-ambientes-reprodut%C3%ADveis/"
markdown_url: "https://ziglang.com.br/instalacao/como-instalar-zig-com-nix-nixos-flakes-e-ambientes-reprodut%C3%ADveis.MD"
description: "Guia completo para instalar o Zig com o gerenciador de pacotes Nix. Cobre NixOS, nix-env, flakes e devshells reprodutíveis."
date: "2026-02-21"
author: "Zig Brasil"
---

# Como Instalar Zig com Nix — NixOS, Flakes e Ambientes Reprodutíveis

Guia completo para instalar o Zig com o gerenciador de pacotes Nix. Cobre NixOS, nix-env, flakes e devshells reprodutíveis.


# 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](/instalacao/). Se busca um método mais simples, veja os guias para [Ubuntu](/instalacao/instalar-zig-linux-ubuntu/), [Fedora](/instalacao/instalar-zig-linux-fedora/) ou [macOS](/instalacao/instalar-zig-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:

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

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

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

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

```bash
nix-env -iA nixpkgs.zig
```

### Verificar a Instalação

```bash
zig version
```

### Instalar o ZLS junto

```bash
nix-env -iA nixpkgs.zls
```

### Listar Versões Disponíveis

```bash
nix-env -qaP 'zig*'
```

### Desinstalar

```bash
nix-env -e zig
```

### Rollback

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

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

```bash
nix-shell -p zig
```

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

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

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

```nix
{
  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

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

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

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

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

```nix
{
  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

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

```nix
{ config, pkgs, ... }:

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

Aplique a configuração:

```bash
sudo nixos-rebuild switch
```

### Instalação via Home Manager

Se usa o Home Manager para gerenciar seu ambiente:

```nix
{ config, pkgs, ... }:

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

Aplique:

```bash
home-manager switch
```

---

## Integração com direnv

O [direnv](https://direnv.net/) 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:

```bash
nix-env -iA nixpkgs.direnv nixpkgs.nix-direnv
```

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

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

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

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

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

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

```bash
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](/erros/).

---

## Próximos Passos

Com o Zig instalado via Nix:

1. **Configure seu editor** — [VS Code](/instalacao/configurar-vscode-zig/) ou [Neovim](/instalacao/configurar-neovim-zig/)
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. **Configure CI/CD** — [GitHub Actions com Zig](/instalacao/zig-ci-github-actions/)
5. **Veja exemplos** — [Receitas](/receitas/)

Se também trabalha com Docker, confira como [usar Zig com Docker](/instalacao/instalar-zig-docker/) para criar imagens de produção otimizadas.