hatch-mojo

A Hatch build hook plugin that compiles Mojo sources during package builds.

Supports Python extension modules and standalone artifacts (shared libraries, executables, etc.).

Installation

uv add hatch-mojo

Quickstart

Add the hook to your pyproject.toml:

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling", "hatch-mojo"]

[tool.hatch.build.targets.wheel.hooks.mojo]
targets = ["wheel"]

[[tool.hatch.build.targets.wheel.hooks.mojo.jobs]]
name = "core"
input = "src/mo/my_pkg/core.mojo"
emit = "python-extension"
module = "my_pkg._core"
include-dirs = ["src/mo"]

Then build:

hatch build -t wheel

Configuration

All configuration lives under [tool.hatch.build.targets.wheel.hooks.mojo] in pyproject.toml.

Global options

[tool.hatch.build.targets.wheel.hooks.mojo]
mojo-bin = "/opt/mojo/bin/mojo"    # path to mojo binary (default: $HATCH_MOJO_BIN or "mojo")
parallel = true                     # compile jobs in parallel
fail-fast = true                    # stop on first failure (only with parallel)
clean-before-build = false          # remove build-dir before compiling
clean-after-build = false           # remove build-dir after compiling
skip-editable = true                # skip Mojo compilation for editable installs
build-dir = "build/mojo"            # working directory for compiled artifacts
targets = ["wheel"]                 # hatch build targets that trigger this hook
include = ["src/mo/**/*.mojo"]      # git-style globs to include
exclude = ["**/experimental*.mojo"] # git-style globs to exclude

Profiles

Profiles define reusable sets of job options. Jobs reference them by name, and profile values are merged into the job config.

[tool.hatch.build.targets.wheel.hooks.mojo.profiles.default]
include-dirs = ["src/mo"]
flags = ["-I", "vendor/include"]

[[tool.hatch.build.targets.wheel.hooks.mojo.jobs]]
name = "core"
profiles = ["default"]
input = "src/mo/my_pkg/core.mojo"
emit = "python-extension"
module = "my_pkg._core"

Jobs

Each job compiles a single Mojo source into an output artifact.

Python extension:

[[tool.hatch.build.targets.wheel.hooks.mojo.jobs]]
name = "core"
input = "src/mo/my_pkg/core.mojo"
emit = "python-extension"
module = "my_pkg._core"
include-dirs = ["src/mo"]

Non-Python artifact (requires an install mapping):

[[tool.hatch.build.targets.wheel.hooks.mojo.jobs]]
name = "cli"
input = "src/mo/my_pkg/cli.mojo"
emit = "executable"
install = { kind = "scripts", path = "my-cli" }

Job options reference

Supported install kinds: package, data, scripts, root, force-include

Runtime library bundling

When building wheels that include Mojo python-extensions, set bundle-libs = true to copy the Mojo runtime libraries into the wheel:

[tool.hatch.build.targets.wheel.hooks.mojo]
bundle-libs = true

This works on both Linux and macOS. On Linux, patchelf sets RPATH on each library. On macOS, install_name_tool rewrites dylib install names and inter-library references to use @rpath.

A NOTICE.mojo-runtime file is automatically included in the wheel alongside the bundled libraries, listing the bundled files and their license terms (Modular Community License). If the SDK directory contains a LICENSE file, it is also copied into the wheel as LICENSE.mojo-runtime.

cibuildwheel

When using cibuildwheel, keep the following in mind:

Linux (manylinux): The Mojo SDK requires manylinux_2_34 or newer due to GLIBCXX requirements. Standard auditwheel repair may reject the wheel — use a retag command instead:

[tool.cibuildwheel.linux]
repair-wheel-command = "python -m wheel tags --remove --platform-tag manylinux_2_34_x86_64 {wheel} && mv {wheel} {dest_dir}"

macOS: With bundle-libs = true, macOS wheels work with standard delocate. No special repair command is needed:

[tool.cibuildwheel.macos]
repair-wheel-command = "delocate-wheel -w {dest_dir} {wheel}"

macOS SIP and DYLD_LIBRARY_PATH: macOS System Integrity Protection (SIP) strips DYLD_LIBRARY_PATH from child processes. Setting it in CIBW_ENVIRONMENT will not propagate to the repair step. If you need it, pass it inline in the repair command:

[tool.cibuildwheel.macos]
repair-wheel-command = "DYLD_LIBRARY_PATH=/path/to/libs delocate-wheel -w {dest_dir} {wheel}"

libstdc++ on manylinux: If the Mojo SDK links against a newer libstdc++ than the manylinux baseline provides, you may need to bundle it from conda-forge. This is a Mojo SDK limitation, not a hatch-mojo issue.

Troubleshooting

License

MIT