{"id":5828,"library":"ziglang","title":"Zig Language Toolchain (Python Wrapper)","description":"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.","status":"active","version":"0.15.2","language":"en","source_language":"en","source_url":"https://github.com/ziglang/zig-pypi","tags":["zig","toolchain","compiler","systems programming","build tools","c/c++ compiler"],"install":[{"cmd":"pip install ziglang","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import ziglang # Does not expose direct Python API for compiler operations","symbol":"ziglang module","correct":"import sys, subprocess\nsubprocess.call([sys.executable, '-m', 'ziglang', '--version'])"}],"quickstart":{"code":"import sys\nimport subprocess\n\n# Run the Zig compiler to print its version\nresult = subprocess.run([sys.executable, '-m', 'ziglang', 'version'], capture_output=True, text=True)\nprint(f\"Zig version via python -m ziglang: {result.stdout.strip()}\")\n\n# Alternatively, use the 'python-zig' wrapper directly (if added to PATH or located)\n# Note: This example assumes 'python-zig' is directly in PATH or located. \n# For robust use, you might need to find its path in the virtual environment's bin/Scripts directory.\ntry:\n    result = subprocess.run(['python-zig', 'version'], capture_output=True, text=True, check=True)\n    print(f\"Zig version via python-zig: {result.stdout.strip()}\")\nexcept FileNotFoundError:\n    print(\"Could not find 'python-zig' directly in PATH. Use 'python -m ziglang' or locate the executable.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running python-zig: {e.stderr.strip()}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of ziglang (due to upstream Zig changes)"},{"fix":"Understand that `ziglang` is a distribution of the executable compiler. For advanced Python-Zig interop, explore dedicated bridging libraries.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}