---
title: "Gerenciador de Pacotes do Zig — Guia Completo"
url: "https://ziglang.com.br/ecossistema/gerenciador-de-pacotes-do-zig-guia-completo/"
markdown_url: "https://ziglang.com.br/ecossistema/gerenciador-de-pacotes-do-zig-guia-completo.MD"
description: "Aprenda a usar o gerenciador de pacotes oficial do Zig: build.zig.zon, dependências, versionamento e publicação de pacotes próprios."
date: "2026-02-21"
author: "Zig Brasil"
---

# Gerenciador de Pacotes do Zig — Guia Completo

Aprenda a usar o gerenciador de pacotes oficial do Zig: build.zig.zon, dependências, versionamento e publicação de pacotes próprios.


# Gerenciador de Pacotes do Zig — Guia Completo

O gerenciador de pacotes do Zig é uma peça fundamental do ecossistema, integrado diretamente ao [sistema de build](/ecossistema/zig-build-system-overview/). Diferente de gerenciadores de pacotes centralizados como npm ou crates.io, o sistema do Zig adota uma abordagem descentralizada baseada em URLs e hashes, garantindo reprodutibilidade total das builds sem depender de um registro central único.

## Arquitetura do Sistema de Pacotes

O gerenciamento de pacotes no Zig é feito através de dois arquivos que trabalham em conjunto:

- **`build.zig.zon`**: Declara as dependências do projeto, incluindo URLs e hashes de integridade
- **`build.zig`**: Configura como as dependências são usadas no processo de compilação

Essa separação permite que o sistema de build seja flexível enquanto as dependências permanecem declarativas e verificáveis.

## Estrutura do build.zig.zon

O arquivo `build.zig.zon` usa o formato ZON (Zig Object Notation), que é essencialmente um subconjunto da sintaxe de inicializadores do Zig:

```zig
.{
    .name = "meu-projeto",
    .version = "1.0.0",
    .minimum_zig_version = "0.13.0",
    .dependencies = .{
        .httpz = .{
            .url = "https://github.com/zig-community/httpz/archive/refs/tags/v0.2.0.tar.gz",
            .hash = "1220a1b2c3d4e5f6...",
        },
        .zap = .{
            .url = "git+https://github.com/zigzap/zap.git#v0.5.0",
            .hash = "1220f1e2d3c4b5a6...",
        },
        .minha_lib_local = .{
            .path = "../minha-lib",
        },
    },
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
        "README.md",
    },
}
```

### Campos Importantes

- **`.name`**: Nome do pacote, usado como identificador
- **`.version`**: Versão semântica do pacote
- **`.minimum_zig_version`**: Versão mínima do compilador necessária
- **`.dependencies`**: Mapa de dependências com URLs ou caminhos locais
- **`.paths`**: Arquivos incluídos quando o pacote é consumido como dependência

## Adicionando Dependências

### Via Comando fetch

A forma mais simples de adicionar uma dependência é usando `zig fetch`:

```bash
# Adicionar dependência e calcular hash automaticamente
zig fetch --save https://github.com/exemplo/lib/archive/refs/tags/v1.0.0.tar.gz

# O comando adiciona automaticamente ao build.zig.zon
```

### Manualmente

Você pode adicionar dependências manualmente ao `build.zig.zon`. Para calcular o hash:

```bash
zig fetch https://github.com/exemplo/lib/archive/refs/tags/v1.0.0.tar.gz
# Retorna o hash que deve ser colocado no campo .hash
```

### Dependências Git

O Zig suporta repositórios Git diretamente:

```zig
.minha_dep = .{
    .url = "git+https://github.com/usuario/repo.git#tag-ou-commit",
    .hash = "1220...",
},
```

### Dependências Locais

Para desenvolvimento com bibliotecas locais:

```zig
.minha_lib = .{
    .path = "../caminho/para/lib",
},
```

## Usando Dependências no build.zig

Após declarar as dependências no `build.zig.zon`, use-as no `build.zig`:

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

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

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

    // Importar dependência
    const httpz = b.dependency("httpz", .{
        .target = target,
        .optimize = optimize,
    });

    // Adicionar módulo ao executável
    exe.root_module.addImport("httpz", httpz.module("httpz"));

    // Para bibliotecas C empacotadas como dependências Zig
    const sqlite = b.dependency("sqlite", .{
        .target = target,
        .optimize = optimize,
    });
    exe.linkLibrary(sqlite.artifact("sqlite3"));

    b.installArtifact(exe);
}
```

No código fonte, use normalmente:

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

pub fn main() !void {
    var server = try httpz.Server.init(std.heap.page_allocator, .{ .port = 8080 });
    defer server.deinit();
    // ...
}
```

## Criando Pacotes para Publicação

Para criar um pacote Zig que outros possam usar como dependência, siga estas práticas:

### Estrutura Recomendada

```
minha-lib/
├── build.zig
├── build.zig.zon
├── src/
│   ├── lib.zig        # Ponto de entrada do módulo
│   └── internal/
│       └── utils.zig
├── tests/
│   └── test_lib.zig
├── LICENSE
└── README.md
```

### build.zig para uma Biblioteca

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

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Expor módulo para consumidores
    _ = b.addModule("minha-lib", .{
        .root_source_file = b.path("src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Testes
    const tests = b.addTest(.{
        .root_source_file = b.path("src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });

    const run_tests = b.addRunArtifact(tests);
    const test_step = b.step("test", "Executar testes");
    test_step.dependOn(&run_tests.step);
}
```

### build.zig.zon para Publicação

```zig
.{
    .name = "minha-lib",
    .version = "0.1.0",
    .minimum_zig_version = "0.13.0",
    .dependencies = .{},
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
    },
}
```

### Publicação

Como o sistema é descentralizado, publique seu pacote em qualquer serviço de hospedagem Git:

1. **GitHub/GitLab**: Crie releases com tags semânticas
2. **Tar archives**: Hospede em qualquer servidor HTTP
3. **Registros comunitários**: Use plataformas como aquila ou astrolabe.pm

## Registros de Pacotes Comunitários

Embora o Zig não tenha um registro central oficial, a comunidade mantém diretórios de pacotes:

- **aquila**: Registro e busca de pacotes Zig
- **astrolabe.pm**: Catálogo de pacotes com busca e metadados
- **GitHub Topics**: Busque por repositórios com a tag "zig-package"

Esses recursos são ótimos para descobrir bibliotecas do [ecossistema](/ecossistema/) como [frameworks web](/ecossistema/httpz-web/), [bibliotecas de criptografia](/ecossistema/zig-crypto-libs/) e [drivers de banco de dados](/ecossistema/zig-database-drivers/).

## Cache e Reprodutibilidade

O gerenciador de pacotes mantém um cache local em `~/.cache/zig/` (Linux) ou equivalente. As dependências são baixadas uma única vez e reutilizadas entre builds.

A verificação de hash garante que:
- Dependências não podem ser alteradas após publicação sem que o hash mude
- Builds são reproduzíveis em qualquer máquina
- Ataques de supply chain são detectáveis

```bash
# Limpar cache se necessário
rm -rf ~/.cache/zig/p/

# Forçar re-download de dependências
zig build --fetch
```

## Dependências Transitivas

O sistema resolve automaticamente dependências transitivas. Se seu projeto depende de A, e A depende de B, o Zig resolve toda a árvore de dependências e garante que não haja conflitos de versão.

## Boas Práticas

1. **Use tags semânticas** para versionar seus pacotes
2. **Declare `.paths` explicitamente** para controlar o que é incluído no pacote
3. **Especifique `minimum_zig_version`** para ajudar consumidores
4. **Teste com múltiplas versões** do compilador usando [zigup](/ecossistema/zigup-version-manager/)
5. **Documente o módulo público** com doc comments no código fonte
6. **Mantenha dependências mínimas** para reduzir a árvore de dependências

## Próximos Passos

Com o gerenciador de pacotes dominado, explore as bibliotecas disponíveis no [ecossistema Zig](/ecossistema/). Consulte nossos [tutoriais](/tutoriais/) para projetos práticos que utilizam dependências externas e veja como projetos reais gerenciam pacotes nos [cases de sucesso](/cases/).