---
title: Zig Package
description: Provision an official Zig distribution and configure Zig as a C and C++ compiler.
---

# Zig Package

The Zig package provisions an exact official Zig host distribution. A global Zig installation is not needed.

Load an exact stable release:

```python
load("@zig@0.16.0", "zig", "zig_cc")
```

Versions must use canonical stable `x.y.z` form. The exact version and host artifact must exist in Zig's official index; aliases, prereleases, ranges, and version or architecture fallback are unsupported.

## `zig`

`zig` is a dependency that provisions the selected distribution and puts its executable directory first in `PATH`. Use it with [`run`](os.md#run) for direct Zig commands:

```python
load("@zig@0.16.0", "zig")
load("@os@1", "run")

run(("zig", "build"), deps=[zig])
```

## `zig_cc`

```python
zig_cc()
zig_cc("target")
```

`zig_cc()` sets `CC` to the managed `zig cc` command and `CXX` to the managed `zig c++` command. It also puts the managed executable directory first in `PATH`. With no argument, it omits `-target` and uses Zig's host default. Pass either no argument or one non-empty target string; `None` is invalid. A target is forwarded as one command field:

```python
zig_cc("x86_64-linux-gnu")
```

This sets `CC` to managed `zig cc -target x86_64-linux-gnu` and `CXX` to managed `zig c++ -target x86_64-linux-gnu`. The target must be valid for Zig. Empty targets, control characters, and target fields containing both single and double quotes are rejected because Go cannot consume those compiler command fields losslessly.

Dependencies apply in declared order, so later dependencies may override `PATH`, `CC`, or `CXX`.

## Distribution Download and Cache

Supported hosts:

- Windows x86-64 (`windows/amd64`)
- Windows ARM64 (`windows/arm64`)
- Linux x86-64 (`linux/amd64`)
- Linux ARM64 (`linux/arm64`)
- macOS ARM64 (`darwin/arm64`)

The requested stable version must have an exact artifact for the host. Unsupported hosts and missing artifacts fail without version or architecture fallback.

Zig's official index is authoritative for artifact filename, size, and SHA-256. xx installs validated distributions in the operating-system user cache under `xx/zig/<host-artifact>/<version>` (for example, `xx/zig/aarch64-macos/0.14.1`). Host-artifact isolation prevents caches copied or shared across host architectures from reusing the wrong compiler. Mirror-list cache files remain directly under `xx/zig`. A valid same-host cached distribution needs no network request. Interactive first-time installation shows download and installation progress.

xx reads the community mirror list from `https://ziglang.org/download/community-mirrors.txt`. The bounded, validated list is cached with a seven-day stale-while-revalidate policy: a fresh list causes no request; a stale list is served immediately while one command-scoped background refresh runs; a missing or invalid cache refreshes synchronously. Refresh failures preserve a stale cache. Archive sources are randomized community mirrors followed by the official download.

Every source must provide both the archive and its `.minisig`. xx verifies the signature with the pinned Zig Software Foundation key, requires the authenticated trusted `file` field to equal the exact archive filename, and checks exact size and SHA-256 from the official index. Every redirect hop must remain HTTPS, and the final archive and signature URLs for a candidate must share the same normalized origin. Extraction is bounded and hardened, and the installed executable must report the requested version. Community mirror operators are untrusted; these checks make mirror use safe.

xx is not fully hermetic. First installation and mirror-list refresh depend on network availability and current official metadata; operating-system cache contents are persistent external input.

## Examples

See [Zig examples](../examples/zig.md) for direct Zig commands and Go CGO builds using Zig compilers.

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/examples/zig.md
Title: Zig Examples
Description: Direct Zig commands and Go CGO builds with a managed Zig distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/packages/go.md
Title: Go Package
Description: Provision an official Go SDK, run or install Go tools, and build Go binaries.

URL: https://withxx.dev/packages/nodejs.md
Title: Node.js Package
Description: Provision official Node.js distributions and run npm and npx tasks.

URL: https://withxx.dev/packages/os.md
Title: OS Package
Description: Run commands and construct isolated task environments.

URL: https://withxx.dev/packages/zig.md
Title: Zig Package
Description: Provision an official Zig distribution and configure Zig as a C and C++ compiler.
-->