Zig Package Manager & (Deep)

Minimal Manifest

Every build.zig.zon file must declare at least the package name, version, and minimum supported Zig version:

.{
    .name = "myproject",
    .version = "0.1.0",
    .minimum_zig_version = "0.15.2",
    .fingerprint = 0x1234567890abcdef,
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
    },
}

The .paths field specifies which files and directories are included when this package is fetched by another project. This inclusion list directly affects the computed package hash—only listed files contribute to the hash, ensuring deterministic content addressing.

Package Identity and Versioning

The .name and .version fields together establish package identity. As of Zig 0.15.2, the package manager does not yet perform automatic version resolution or deduplication, but these fields prepare for future enhancements and help human maintainers understand package relationships.

The .minimum_zig_version field communicates compatibility expectations. When a package declares a minimum version, the build system will refuse to proceed if the current Zig toolchain is older, preventing obscure compilation failures due to missing features or changed semantics.

The .fingerprint field (omitted in the minimal example but shown in the template) is a unique identifier generated once when the package is created and never changed thereafter. This fingerprint enables unambiguous detection of package forks and updates, protecting against hostile forks that attempt to impersonate upstream projects.

Declaring Dependencies

Dependencies are declared in the .dependencies struct. Each dependency must provide either a .url and .hash pair (for remote packages) or a .path (for local packages):

.{
    .name = "consumer",
    .version = "0.2.0",
    .minimum_zig_version = "0.15.2",
    .dependencies = .{
        // Path-based dependency (local development)
        .mylib = .{
            .path = "../mylib",
        },
        // URL-based dependency would look like:
        // .known_folders = .{
        //     .url = "https://github.com/ziglibs/known-folders/archive/refs/tags/v1.1.0.tar.gz",
        //     .hash = "1220c1aa96c9cf0a7df5848c9d50e0e1f1e8b6ac8e7f5e4c0f4c5e6f7a8b9c0d",
        // },
    },
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

URL-based dependencies are fetched from the network, verified against the provided hash, and cached globally. Path-based dependencies reference a directory relative to the build root, useful during local development or when vendoring dependencies.

The hash uses the multihash format, where the prefix 1220 indicates SHA-256. This content-addressed approach ensures that packages are identified by their contents rather than their URLs, making the package manager resilient to URL changes and mirror availability.

Lazy vs Eager Dependencies

By default, all declared dependencies are eager: they are fetched and verified before the build script runs. For optional dependencies that are only needed under certain conditions (e.g., debugging tools, benchmarking utilities, or platform-specific extensions), you can mark them as lazy with .lazy = true:

.{
    .name = "app",
    .version = "1.0.0",
    .minimum_zig_version = "0.15.2",
    .dependencies = .{
        // Eager dependency: always fetched
        .core = .{
            .path = "../core",
        },
        // Lazy dependency: only fetched when actually used
        .benchmark_utils = .{
            .path = "../benchmark_utils",
            .lazy = true,
        },
        .debug_visualizer = .{
            .path = "../debug_visualizer",
            .lazy = true,
        },
    },
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

Lazy dependencies are not fetched until build.zig explicitly requests them via b.lazyDependency(). If the build script never calls lazyDependency() for a given package, that package remains unfetched, saving download time and disk space.

This two-phase approach allows the build script to declare optional dependencies without forcing all users to download them. When a lazy dependency is requested but not yet available, the build runner will fetch it, then re-run the build script—a transparent process that balances flexibility with determinism.

1. Parse and Validate

When you run zig build, the compiler first parses build.zig.zon as a ZON literal (see build_runner.zig). This parse step validates syntax and ensures all required fields are present. The compiler checks:

• Each dependency has either .url+.hash or .path (but not both)
• Hash strings use valid multihash encoding
• The .minimum_zig_version is not newer than the running toolchain

2. Fetch and Verify

For each eager dependency with a .url, the build runner:

1. Computes a unique cache key from the hash

2. Checks if the package exists in the global cache (~/.cache/zig/p/<hash>/ on Unix-like systems)

3. If not cached, downloads the URL contents

4. Extracts the archive if needed (supports .tar.gz, .tar.xz, .zip)

5. Applies the .paths filter from the dependency’s own build.zig.zon

6. Computes the hash of the filtered content

7. Verifies it matches the declared .hash field

8. Stores the verified content in the global cache

If hash verification fails, the build aborts with a clear error message indicating hash mismatch. This prevents supply-chain attacks where a compromised mirror serves different content.

Path-based dependencies skip the fetch step—they are always available relative to the build root.

3. Cache Lookup and Reuse

Once a package is cached, subsequent builds reuse the cached version without re-downloading or re-verifying. The global cache is shared across all Zig projects on the system, so fetching a popular dependency once benefits all projects.

The cache directory structure is content-addressed: each package’s hash directly maps to a cache subdirectory. This makes cache management transparent and predictable—you can inspect cached packages or clear the cache without risk of corrupting build state.

4. Dependency Graph Construction

After all eager dependencies are available, the build runner constructs a dependency graph. Each package’s build.zig is loaded as a Zig module, and the build() function is called to register artifacts and steps.

Lazy dependencies are not loaded at this stage. Instead, the build runner marks them as "potentially needed" and proceeds. If build.zig calls b.lazyDependency() for a lazy package that hasn’t been fetched yet, the build runner records the request, completes the current build pass, fetches the lazy dependencies, and re-runs the build script.

This deferred-fetch mechanism allows build scripts to conditionally load dependencies based on user options or target characteristics without forcing all users to download every optional package.

Internally, Zig records dependencies on ZON manifests and other dependees inside the InternPool, so that changes to build.zig.zon or embedded files can invalidate only the analysis units that depend on them:

ZON files participate in the same incremental compilation graph as source hashes and embedded files: updating build.zig.zon updates the corresponding zon_file_deps entries, which in turn mark dependent analysis units and build steps as outdated.

More broadly, ZON manifests are just one of several dependee categories that the compiler tracks; at a high level these groups look like this:

The package manager sits on top of this infrastructure: .dependencies entries in build.zig.zon ultimately translate into ZON-file dependees and cached content that participate in the same dependency system.

Conceptual Example: Resolution Pipeline

The following example demonstrates the logical flow of dependency resolution:

// Conceptual example showing the dependency resolution pipeline
const std = @import("std");

const DependencyState = enum {
    declared, // Listed in build.zig.zon
    downloading, // URL being fetched
    verifying, // Hash being checked
    cached, // Stored in global cache
    available, // Ready for use
};

const Dependency = struct {
    name: []const u8,
    url: ?[]const u8,
    path: ?[]const u8,
    hash: ?[]const u8,
    lazy: bool,
    state: DependencyState,
};

pub fn main() !void {
    std.debug.print("--- Zig Package Manager Resolution Pipeline ---\n\n", .{});

    // Stage 1: Parse build.zig.zon
    std.debug.print("1. Parse build.zig.zon dependencies\n", .{});
    var deps = [_]Dependency{
        .{
            .name = "core",
            .path = "../core",
            .url = null,
            .hash = null,
            .lazy = false,
            .state = .declared,
        },
        .{
            .name = "utils",
            .url = "https://example.com/utils.tar.gz",
            .path = null,
            .hash = "1220abcd...",
            .lazy = false,
            .state = .declared,
        },
        .{
            .name = "optional_viz",
            .url = "https://example.com/viz.tar.gz",
            .path = null,
            .hash = "1220ef01...",
            .lazy = true,
            .state = .declared,
        },
    };

    // Stage 2: Resolve eager dependencies
    std.debug.print("\n2. Resolve eager dependencies\n", .{});
    for (&deps) |*dep| {
        if (!dep.lazy) {
            std.debug.print("   - {s}: ", .{dep.name});
            if (dep.path) |p| {
                std.debug.print("local path '{s}' → available\n", .{p});
                dep.state = .available;
            } else if (dep.url) |_| {
                std.debug.print("fetching → verifying → cached → available\n", .{});
                dep.state = .available;
            }
        }
    }

    // Stage 3: Lazy dependencies deferred
    std.debug.print("\n3. Lazy dependencies (deferred until used)\n", .{});
    for (deps) |dep| {
        if (dep.lazy) {
            std.debug.print("   - {s}: waiting for lazyDependency() call\n", .{dep.name});
        }
    }

    // Stage 4: Build script execution triggers lazy fetch
    std.debug.print("\n4. Build script requests lazy dependency\n", .{});
    std.debug.print("   - optional_viz requested → fetching now\n", .{});

    // Stage 5: Cache lookup
    std.debug.print("\n5. Cache locations\n", .{});
    std.debug.print("   - Global: ~/.cache/zig/p/<hash>/\n", .{});
    std.debug.print("   - Project: .zig-cache/\n", .{});

    std.debug.print("\n=== Resolution Complete ===\n", .{});
}

$ zig run 07_resolution_pipeline_demo.zig

=== Zig Package Manager Resolution Pipeline ===

1. Parse build.zig.zon dependencies

2. Resolve eager dependencies
   - core: local path '../core' → available
   - utils: fetching → verifying → cached → available

3. Lazy dependencies (deferred until used)
   - optional_viz: waiting for lazyDependency() call

4. Build script requests lazy dependency
   - optional_viz requested → fetching now

5. Cache locations
   - Global: ~/.cache/zig/p/<hash>/
   - Project: .zig-cache/

=== Resolution Complete ===

This conceptual model matches the actual implementation in the build runner and standard library.

Using

For eager dependencies, use b.dependency(name, args) where name matches a key in .dependencies and args is a struct containing build options to pass down to the dependency’s build script:

const std = @import("std");

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

    // Fetch the dependency defined in build.zig.zon
    const mylib_dep = b.dependency("mylib", .{
        .target = target,
        .optimize = optimize,
    });

    // Get the module from the dependency
    const mylib_module = mylib_dep.module("mylib");

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

    // Import the dependency module
    exe.root_module.addImport("mylib", mylib_module);

    b.installArtifact(exe);

    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }

    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);
}

The b.dependency() call returns a *Dependency, which provides methods to access the dependency’s artifacts (.artifact()), modules (.module()), lazy paths (.path()), and named write-files (.namedWriteFiles()).

The args parameter forwards build options to the dependency, allowing you to configure the dependency’s target, optimization level, or custom features. This ensures the dependency is built with compatible settings.

Using

For lazy dependencies, use b.lazyDependency(name, args) instead. This function returns ?*Dependency—null if the dependency has not yet been fetched:

const std = @import("std");

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

    // Core dependency is always loaded
    const core_dep = b.dependency("core", .{
        .target = target,
        .optimize = optimize,
    });

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

    exe.root_module.addImport("core", core_dep.module("core"));
    b.installArtifact(exe);

    // Conditionally use lazy dependencies based on build options
    const enable_benchmarks = b.option(bool, "benchmarks", "Enable benchmark mode") orelse false;
    const enable_debug_viz = b.option(bool, "debug-viz", "Enable debug visualizations") orelse false;

    if (enable_benchmarks) {
        // lazyDependency returns null if not yet fetched
        if (b.lazyDependency("benchmark_utils", .{
            .target = target,
            .optimize = optimize,
        })) |bench_dep| {
            exe.root_module.addImport("benchmark", bench_dep.module("benchmark"));
        }
    }

    if (enable_debug_viz) {
        if (b.lazyDependency("debug_visualizer", .{
            .target = target,
            .optimize = optimize,
        })) |viz_dep| {
            exe.root_module.addImport("visualizer", viz_dep.module("visualizer"));
        }
    }

    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());

    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);
}

When lazyDependency() returns null, the build runner records the request and re-runs the build script after fetching the missing dependency. On the second pass, lazyDependency() will succeed, and the build proceeds normally.

This pattern allows build scripts to conditionally include optional features without forcing all users to fetch those dependencies:

$ zig build                          # Core functionality only
$ zig build -Dbenchmarks=true        # Fetches benchmark_utils if needed
$ zig build -Ddebug-viz=true         # Fetches debug_visualizer if needed

Multihash Format

Zig uses the multihash format to encode hash digests. A multihash string consists of:

1. A prefix indicating the hash algorithm (e.g., 1220 for SHA-256)

2. The hex-encoded hash digest

For SHA-256, the prefix 1220 breaks down as:

• 12 (hex) = SHA-256 algorithm identifier
• 20 (hex) = 32 bytes = SHA-256 digest length

The following example demonstrates conceptual hash computation (the actual implementation lives in the build runner and cache system):

// This example demonstrates how hash verification works conceptually.
// In practice, Zig handles this automatically during `zig fetch`.

const std = @import("std");

pub fn main() !void {
    // Simulate fetching a package
    const package_contents = "This is the package source code.";

    // Compute the hash
    var hasher = std.crypto.hash.sha2.Sha256.init(.{});
    hasher.update(package_contents);
    var digest: [32]u8 = undefined;
    hasher.final(&digest); // Format as hex for display
    std.debug.print("Package hash: {x}\n", .{digest});
    std.debug.print("Expected hash in build.zig.zon: 1220{x}\n", .{digest});
    std.debug.print("\nNote: The '1220' prefix indicates SHA-256 in multihash format.\n", .{});
}

$ zig run 06_hash_verification_example.zig

Package hash: 69b2de89d968f316b3679f2e68ecacb50fd3064e0e0ee7922df4e1ced43744d2
Expected hash in build.zig.zon: 122069b2de89d968f316b3679f2e68ecacb50fd3064e0e0ee7922df4e1ced43744d2

Note: The `1220` prefix indicates SHA-256 in multihash format.

The compiler uses a similar "hash → compare → reuse" pattern for incremental compilation when deciding whether to reuse cached IR for a declaration:

This is conceptually the same as package hashing: for both source and dependencies, Zig computes a content hash, compares it with a cached value, and either reuses cached artifacts or recomputes them.

In practice, you rarely need to compute hashes manually. The zig fetch command automates this:

$ zig fetch https://example.com/package.tar.gz

Zig downloads the package, computes the hash, and prints the complete multihash string you can copy into build.zig.zon.

Content Addressing

Because packages are identified by hash rather than URL, the package manager is inherently resilient to URL changes, mirror failures, and upstream relocations. As long as some mirror provides content matching the hash, the package is usable.

This content-addressed design also prevents certain classes of supply-chain attacks: an attacker who compromises a single mirror cannot inject malicious code unless they also break the hash function (SHA-256), which is computationally infeasible.

The same content-addressing principle appears elsewhere in Zig’s implementation: the InternPool stores each distinct type or value exactly once and identifies it by an index, with dependency tracking built on top of these content-derived keys rather than on file paths or textual names.

Lockfile Semantics and Transitive Dependencies

As of Zig 0.15.2, the package manager does not generate a separate lockfile—build.zig.zon itself serves as the lockfile. Each dependency’s hash locks its content, and transitive dependencies are locked by the direct dependency’s hash (since the direct dependency’s build.zig.zon specifies its own dependencies).

This approach simplifies the mental model: there is one source of truth (build.zig.zon), and the hash chain ensures transitivity without additional metadata files.

Future Zig versions may introduce explicit lockfiles for advanced use cases (e.g., tracking resolved URLs or deduplicating transitive dependencies), but the core content-addressing principle will remain. v0.15.2

Offline Builds and Cache Portability

Once all dependencies are cached, you can build offline indefinitely. The global cache persists across projects, so fetching a dependency once benefits all future projects that use it.

To prepare for offline builds:

1. Run zig build --fetch to fetch all declared dependencies without building

2. Verify the cache is populated: ls ~/.cache/zig/p/

3. Disconnect from the network and run zig build normally

If you need to transfer a project with its dependencies to an air-gapped environment, you can:

1. Fetch all dependencies on a networked machine

2. Archive the ~/.cache/zig/p/ directory

3. Extract the archive on the air-gapped machine to the same cache location

4. Run zig build normally

Fetching and Saving Dependencies

To add a new dependency:

$ zig fetch --save https://github.com/example/package/archive/v1.0.0.tar.gz

This command:

1. Downloads the URL

2. Computes the hash

3. Adds an entry to .dependencies in build.zig.zon

4. Saves the package name and hash

You can then reference the dependency by name in build.zig.

Fetching Without Saving

To fetch a URL and print its hash without modifying build.zig.zon:

$ zig fetch https://example.com/package.tar.gz

This is useful for verifying package integrity or preparing vendored dependencies.

Recursive Fetch

To fetch all dependencies transitively (including dependencies of dependencies):

$ zig build --fetch

This populates the cache with everything needed for a complete build, ensuring offline builds will succeed.