Tutorial: your first module

This tutorial creates a tiny extension module that exposes hello(name).

Prerequisites

Zig 0.15.x.
Python 3.14.
uv for project init and running the CLI via uvx.
Network access for zig fetch (or pass --alloconda-path).

1) Initialize a Python project (uv)

Start by creating a pyproject.toml with uv:

mkdir hello_alloconda
cd hello_alloconda
uv init

uv init writes a pyproject.toml with basic project metadata, including the project name that alloconda init will reuse. alloconda init will also add the build backend stanza automatically.

2) Scaffold the Zig project

From a working directory, run:

uvx alloconda init

If you want to use a local alloconda checkout during development, pass --alloconda-path ../alloconda. Otherwise alloconda init will pin the dependency via zig fetch.

alloconda init writes:

build.zig
build.zig.zon
src/root.zig

The default module name is _<project_name> (so _hello_alloconda here).

alloconda init creates src/<project_name>/__init__.py so the CLI can locate the package directory. If you prefer a different layout, move the package and set tool.alloconda.package-dir in pyproject.toml.

4) Build and import

uvx alloconda build
uv run python -c "import hello_alloconda; print(hello_alloconda.hello('alloconda'))"

If alloconda build cannot infer your package directory, pass it explicitly:

uvx alloconda build --package-dir src/hello_alloconda

The CLI copies the built extension into the package directory and generates an __init__.py that re-exports the extension module.

If you prefer an editable install, use:

uvx alloconda develop
uv run python -c "import hello_alloconda; print(hello_alloconda.hello('alloconda'))"

5) Edit the module

Open src/root.zig and add new functions or classes using py.method and py.class. The next chapters show the available patterns.

6) Cross-compile your first wheel matrix

Alloconda can build a multi-platform wheel matrix from one machine. Start with a dry run to see the matrix:

uvx alloconda wheel-all --python-version 3.14 --include-musllinux --include-windows --dry-run

Then run the build (and fetch any missing headers automatically):

uvx alloconda wheel-all --python-version 3.14 --include-musllinux --include-windows --fetch

For detailed targeting and configuration, see the cross-compilation chapter.

Keyboard shortcuts

Alloconda