Install & Compatibility
Where this runs
tested against v0.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.018s · 414.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.0s · import 0.014s · 415MB
413MB installed
● package 413MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ziglang module
✓ import sys, subprocess
subprocess.call([sys.executable, '-m', 'ziglang', '--version'])
✗ import ziglang # Does not expose direct Python API for compiler operations
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.
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()}")
zig --version
Debug
Known issues
gotchaThe `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.fixUse `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.
affects: All versions
breakingThe 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.fixPin 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.
affects: All versions of ziglang (due to upstream Zig changes)
gotchaThe `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`.fixUnderstand that `ziglang` is a distribution of the executable compiler. For advanced Python-Zig interop, explore dedicated bridging libraries.
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'zig'
The 'zig' executable provided by the 'ziglang' package is not automatically added to the system's PATH, and direct calls via 'subprocess' or 'os.system' will fail if not given the full path.
fixUse 'ziglang.zig_path' to retrieve the full path to the executable when invoking 'zig' via 'subprocess.run([ziglang.zig_path, ...])'.
ModuleNotFoundError: No module named 'zig'
The user is attempting to import a module named 'zig', possibly confusing the 'zig' executable or language with the actual Python package name, which is 'ziglang'.
fixThe correct Python package to import is 'ziglang'. Use 'import ziglang'.
PermissionError: [Errno 13] Permission denied: '/path/to/venv/lib/pythonX.Y/site-packages/ziglang/zig/zig'
The 'zig' executable file installed by the 'ziglang' package lacks execute permissions in the current environment, preventing the Python process from running it.
fixEnsure the 'zig' executable has appropriate execute permissions. Reinstalling 'ziglang' in a fresh virtual environment ('pip install --force-reinstall ziglang') often resolves such issues by correctly setting file permissions during installation. Upgrade
Version history
0.16.0latest on PyPI · released Apr 15, 2026
Audit
Dependencies
No dependency data recorded yet.