Installation¶

Requirements¶

Zig 0.13.0 or later
Python 3.8 or later (with development headers)

Python Version Support

PyOZ supports Python 3.8 through 3.13. Testing is performed on Python 3.9 - 3.13.

Installing Zig¶

Linux¶

# Download from ziglang.org
wget https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
tar xf zig-linux-x86_64-0.13.0.tar.xz
export PATH=$PATH:$(pwd)/zig-linux-x86_64-0.13.0

Or use your package manager:

# Ubuntu/Debian (may have older version)
sudo apt install zig

# Arch Linux
sudo pacman -S zig

macOS¶

# Homebrew
brew install zig

# Or download from ziglang.org

Windows¶

Download from ziglang.org and add to PATH.

Installing Python Development Headers¶

Linux¶

# Ubuntu/Debian
sudo apt install python3-dev

# Fedora
sudo dnf install python3-devel

# Arch Linux
sudo pacman -S python

macOS¶

Python development headers are included with the system Python or Homebrew Python.

Windows¶

Install Python from python.org with the "Install development files" option.

Setting Up a PyOZ Project¶

Option 1: Add as Zig Dependency¶

Add PyOZ to your build.zig.zon:

.{
    .name = "my-python-extension",
    .version = "0.1.0",
    .dependencies = .{
        .PyOZ = .{
            .url = "https://github.com/dzonerzy/PyOZ/archive/refs/tags/v0.4.0.tar.gz",
            .hash = "...", // Get hash from release
        },
    },
}

Then in your build.zig:

const std = @import("std");

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

    const pyoz_dep = b.dependency("PyOZ", .{
        .target = target,
        .optimize = optimize,
    });

    const lib = b.addSharedLibrary(.{
        .name = "mymodule",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    lib.root_module.addImport("PyOZ", pyoz_dep.module("PyOZ"));

    // Link Python
    lib.linkSystemLibrary("python3");
    lib.addIncludePath(.{ .cwd_relative = "/usr/include/python3.10" });

    b.installArtifact(lib);
}

Option 2: Clone the Repository¶

git clone https://github.com/dzonerzy/PyOZ.git
cd PyOZ
zig build example  # Build the example module

Verifying Installation¶

After building, test your module:

cd zig-out/lib
python3 -c "import mymodule; print(mymodule.add(2, 3))"

Next Steps¶

Continue to the Quick Start guide to build your first PyOZ module.