Zig Language Toolchain (Python Wrapper)

0.15.2 · active · verified Tue Apr 14

The `ziglang` Python package redistributes the official Zig programming language toolchain, enabling Python projects to use Zig as a build dependency. It provides access to the Zig compiler and related utilities, including `zig cc` for C/C++ compilation, without requiring a separate system-wide Zig installation. The current version is 0.15.2, and new versions are released periodically to bundle updates to the Zig toolchain.

Warnings

gotcha The `ziglang` Python package installs the Zig compiler as a binary wrapper named `python-zig` to prevent conflicts with any system-wide `zig` installations. Always use `python -m ziglang` or explicitly invoke `python-zig` to access the bundled toolchain.
Fix: Use `subprocess.call([sys.executable, '-m', 'ziglang', ...])` or ensure you call the `python-zig` executable instead of `zig` directly if you intend to use the bundled version.
breaking The Zig programming language itself is pre-1.0 and frequently introduces breaking changes to its language, standard library, and build system. While the `ziglang` Python package bundles a specific Zig toolchain version, updating the `ziglang` Python package may update the underlying Zig version, potentially breaking existing Zig code or build scripts that rely on older Zig features.
Fix: Pin the `ziglang` package to a specific version (e.g., `ziglang==0.15.2`) for stability in CI/CD. Regularly consult the official Zig release notes when upgrading `ziglang` to understand potential impacts on your Zig codebase or build processes.
gotcha The `ziglang` package provides the Zig *toolchain*, not a Python API for writing Zig code or direct FFI. For closer integration (e.g., compiling Zig code into Python extensions), consider libraries like `import-zig` or `setuptools-zig`, which build upon `ziglang`.
Fix: Understand that `ziglang` is a distribution of the executable compiler. For advanced Python-Zig interop, explore dedicated bridging libraries.

Install

pip install ziglang Install latest version

Imports

ziglang module
```
import sys, subprocess
subprocess.call([sys.executable, '-m', 'ziglang', '--version'])
```
The `ziglang` package primarily provides the Zig toolchain executable. Interaction is typically via `subprocess` calls to the `python-zig` wrapper or `python -m ziglang`, not by importing classes or functions directly from the `ziglang` module itself for compiler operations.

Quickstart

This quickstart demonstrates how to invoke the bundled Zig toolchain using the `ziglang` Python package. It shows two primary methods: using Python's module execution (`python -m ziglang`) and directly calling the `python-zig` wrapper executable.

import sys
import subprocess

# Run the Zig compiler to print its version
result = subprocess.run([sys.executable, '-m', 'ziglang', 'version'], capture_output=True, text=True)
print(f"Zig version via python -m ziglang: {result.stdout.strip()}")

# Alternatively, use the 'python-zig' wrapper directly (if added to PATH or located)
# Note: This example assumes 'python-zig' is directly in PATH or located. 
# For robust use, you might need to find its path in the virtual environment's bin/Scripts directory.
try:
    result = subprocess.run(['python-zig', 'version'], capture_output=True, text=True, check=True)
    print(f"Zig version via python-zig: {result.stdout.strip()}")
except FileNotFoundError:
    print("Could not find 'python-zig' directly in PATH. Use 'python -m ziglang' or locate the executable.")
except subprocess.CalledProcessError as e:
    print(f"Error running python-zig: {e.stderr.strip()}")

view raw JSON →