---
title: "zig fetch em Zig — O que é e Como Usar"
url: "https://ziglang.com.br/glossario/zig-fetch-em-zig-o-que-%C3%A9-e-como-usar/"
markdown_url: "https://ziglang.com.br/glossario/zig-fetch-em-zig-o-que-%C3%A9-e-como-usar.MD"
description: "Entenda o comando zig fetch: baixar dependências e obter hashes para o build.zig.zon. Gerenciamento de pacotes em Zig. Guia pt-BR."
date: "2026-02-21"
author: "Zig Brasil"
---

# zig fetch em Zig — O que é e Como Usar

Entenda o comando zig fetch: baixar dependências e obter hashes para o build.zig.zon. Gerenciamento de pacotes em Zig. Guia pt-BR.


# zig fetch em Zig — O que é e Como Usar

## Definição

**zig fetch** é o comando da toolchain do Zig usado para **baixar pacotes** de uma URL e calcular o **hash de integridade** necessário para o arquivo `build.zig.zon`. Quando você adiciona uma nova dependência ao seu projeto, `zig fetch` baixa o arquivo, verifica o conteúdo e exibe o hash que deve ser incluído na configuração.

## Por que zig fetch Importa

1. **Obter hashes**: Calcula o hash exato para garantir integridade das dependências.
2. **Cache local**: Dependências são armazenadas em cache e reutilizadas entre builds.
3. **Verificação**: Garante que o conteúdo baixado é exatamente o esperado.
4. **Simplicidade**: Um único comando para adicionar dependências ao projeto.

## Exemplo Prático

### Baixar Dependência e Obter Hash

```bash
# Baixar pacote e exibir o hash
zig fetch https://github.com/zigzap/zap/archive/refs/tags/v0.5.0.tar.gz

# Saída: hash como 1220abcdef...
# Copie este hash para o build.zig.zon
```

### Adicionar ao build.zig.zon

```zig
.{
    .name = "meu-projeto",
    .version = "0.1.0",

    .dependencies = .{
        .zap = .{
            .url = "https://github.com/zigzap/zap/archive/refs/tags/v0.5.0.tar.gz",
            // Cole o hash obtido pelo zig fetch
            .hash = "1220abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
        },
    },

    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}
```

### Salvar Diretamente no build.zig.zon

```bash
# Com --save, adiciona diretamente ao build.zig.zon
zig fetch --save https://github.com/user/repo/archive/refs/tags/v1.0.tar.gz

# Com --save=nome, especifica o nome da dependência
zig fetch --save=minha_lib https://github.com/user/lib/archive/v2.0.tar.gz
```

## Opções do Comando

| Opção | Descrição |
|-------|-----------|
| `--save` | Salva a dependência no build.zig.zon |
| `--save=nome` | Salva com nome específico |
| `--debug-hash` | Mostra detalhes do cálculo do hash |

## Armadilhas Comuns

- **URL do arquivo, não do repositório**: Use a URL do arquivo `.tar.gz`, não a URL da página do GitHub.
- **Hash muda com o conteúdo**: Se o mantenedor recriar a tag/release, o hash pode mudar. Prefira releases estáveis.
- **Rede necessária**: O primeiro fetch requer internet. Após isso, o cache local é usado.
- **Formato do hash**: O hash começa com `1220` seguido de caracteres hexadecimais. É um hash multihash (SHA-256).

## Termos Relacionados

- [build.zig.zon](/glossario/build-zig-zon/) — Manifesto onde o hash é declarado
- [build.zig](/glossario/build-zig/) — Onde a dependência é usada
- [ZON](/glossario/zon/) — Formato do manifesto
- [zig build](/glossario/zig-build/) — Comando que resolve dependências automaticamente

## Fontes de Dependências Suportadas

O `zig fetch` suporta diferentes fontes de dependências. Além de arquivos `.tar.gz` hospedados no GitHub ou em qualquer servidor HTTP, é possível usar arquivos `.tar.xz` e `.tar.zst`. A URL pode apontar para qualquer servidor público — não há dependência de um registro central como crates.io ou npmjs.com. Isso significa que você pode hospedar suas próprias bibliotecas em qualquer infraestrutura.

## Como o Hash Funciona

O hash gerado pelo `zig fetch` usa o formato **multihash** com SHA-256. O prefixo `1220` indica que o algoritmo é SHA-256 (0x12) com comprimento de 32 bytes (0x20). O restante é o digest hexadecimal do conteúdo do arquivo comprimido.

Essa abordagem garante que qualquer alteração no arquivo — mesmo de um único byte — produza um hash completamente diferente. O sistema de build usa esse hash para verificar a integridade antes de extrair e usar a dependência, prevenindo ataques de substituição ou corrupção de arquivos em trânsito.

## Fluxo Completo de Adição de Dependência

```bash
# 1. Encontrar a URL do release desejado (GitHub, GitLab, etc.)
# 2. Rodar zig fetch para obter o hash
zig fetch --save=zig_clap https://github.com/Hejsil/zig-clap/archive/refs/tags/0.9.1.tar.gz

# 3. O arquivo build.zig.zon é atualizado automaticamente com --save
# 4. Usar a dependência no build.zig
```

```zig
// No build.zig, referenciar a dependência pelo nome declarado no .zon
const clap_dep = b.dependency("zig_clap", .{
    .target = target,
    .optimize = optimize,
});
const exe = b.addExecutable(.{
    .name = "meu-app",
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("clap", clap_dep.module("clap"));
b.installArtifact(exe);
```

## Comparação com Outros Gerenciadores

Em Rust, `cargo add` atualiza o `Cargo.toml` com a versão desejada. Em Go, `go get` baixa o módulo e atualiza `go.sum`. O `zig fetch` é conceitualmente similar, mas opera com URLs diretas em vez de um registro central como crates.io ou pkg.go.dev. Isso dá mais controle sobre a origem das dependências, mas exige que você conheça a URL exata do release.

## Cache de Dependências

Após o primeiro `zig fetch`, o conteúdo é armazenado no cache global do Zig (geralmente `~/.cache/zig/` no Linux/macOS ou `%LOCALAPPDATA%\zig\` no Windows). Builds subsequentes — inclusive em outros projetos que usam a mesma dependência com o mesmo hash — reutilizam o cache sem fazer download novamente.

## Tutoriais Relacionados

- [Zig Packaging](/tutoriais/zig-packaging/)
- [Zig Build System](/tutoriais/zig-build-system/)
- [Introdução ao Zig](/tutoriais/introducao-ao-zig/)