hatch-mojo 0.1.0

Hatch build hook for compiling Mojo sources into Python and native artifacts

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 = ".hatch_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

Option	Type	Description
name	string	Unique identifier for the job
input	string	Path to the Mojo source file (supports globs)
emit	string	python-extension, shared-lib, static-lib, object, executable
output	string	Explicit output path (overrides default)
module	string	Dotted import path (required for python-extension)
install	object	Install mapping for non-Python artifacts: { kind, path }
profiles	list	Profile names to inherit settings from
include-dirs	list	Additional include directories passed as -I
defines	list	Values passed as -D flags to the compiler
flags	list	Extra flags passed to mojo build
env	object	Environment variables set during compilation
platforms	list	Restrict job to specific sys.platform values
arch	list	Restrict job to specific platform.machine() values
marker	string	PEP 508 marker expression for conditional inclusion
depends-on	list	Job names that must complete before this one

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

Troubleshooting

Error	Fix
mojo executable not found	Set mojo-bin, HATCH_MOJO_BIN, or add mojo to PATH
No build jobs resolved	Check input paths, include/exclude globs, and targets
unknown dependencies	Ensure depends-on references valid job names
Wheel missing binaries	Set module for extension jobs or install for non-Python jobs

License

MIT