maturin-action

June 19, 2026 · View on GitHub

GitHub Action to install and run a custom maturin command with built-in support for cross compilation.

Usage

- uses: PyO3/maturin-action@v1
  with:
    command: build
    args: --release

To generate a GitHub Actions workflow for your project, try the maturin generate-ci github command.

mkdir -p .github/workflows
maturin generate-ci github > .github/workflows/CI.yml

Examples

If you want to build and publish a Python extension module for common Python versions, operating systems, and CPU architectures, take a look at the following examples:

messense/crfs-rs: PyO3 abi3 wheel example
messense/rjmespath-rs: PyO3 abi3 wheel with Rust nightly toolchain example
astral-sh/uv: Hardened binary publishing example
milesgranger/pyrus-cramjam: PyO3 non-abi3 wheel example
messense/auditwheel-symbols: bin binding example using MUSL libc
adriangb/graphlib2: PyO3 abi3 wheel
pydantic/pydantic-core: PyO3 non-abi3 wheel with PyPy support example
messense/py-dissimilar: PyO3 non-abi3 wheel with PyPy support example

Inputs

Name	Required	Description	Type	Default
command	No	`maturin` command to run	string	`build`
args	No	Arguments to pass to `maturin` subcommand	string
maturin-version	No	The version of `maturin` to use. Must match a tagged release	string	`latest`
manylinux	No	Control the manylinux platform tag on linux, ignored on other platforms, use `auto` to build for lowest compatible	string	Defaults to `auto` for the `publish` command
target	No	The `--target` option for Cargo	string
container	No	manylinux docker container image name	string	Default depends on `target` and `manylinux` options, Set to `off` to disable manylinux docker build and build on the host instead.
docker-options	No	Additional Docker run options, for passing environment variables and etc.	string
rust-toolchain	No	Rust toolchain name.	string	Defaults to `stable` for Docker build. To use the latest available version for the host build, the user must specify this in the CI config or repo config.
rustup-components	No	Rustup components	string	Defaults to empty
working-directory	No	The working directory to run the command in	string	Defaults to the root of the repository
sccache	No	Enable sccache for faster builds	boolean	Defaults to `false`
before-script-linux	No	Script to run before the maturin command on Linux	string

`manylinux` Docker container

By default, this action uses the following containers for supported architectures and manylinux versions.

Architecture	Manylinux version	Default container	Note
x86_64	2010/2_12	quay.io/pypa/manylinux2010_x86_64:latest
x86_64	2014/2_17	quay.io/pypa/manylinux2014_x86_64:latest
x86_64	2_24	quay.io/pypa/manylinux_2_24_x86_64:latest	Deprecated
x86_64	2_28	quay.io/pypa/manylinux_2_28_x86_64:latest
i686	2010/2_12	quay.io/pypa/manylinux2010_i686:latest
i686	2014/2_17	quay.io/pypa/manylinux2014_i686:latest
i686	2_24	quay.io/pypa/manylinux_2_24_i686:latest	Deprecated
i686	2_28	quay.io/pypa/manylinux_2_28_i686:latest
aarch64	2014/2_17	ghcr.io/rust-cross/manylinux2014-cross:aarch64
aarch64	2_24	messense/manylinux_2_24-cross:aarch64	Deprecated
aarch64	2_28	ghcr.io/rust-cross/manylinux_2_28-cross:aarch64
armv7l	2014/2_17	ghcr.io/rust-cross/manylinux2014-cross:armv7
armv7l	2_24	messense/manylinux_2_24-cross:armv7	Deprecated
armv7l	2_28	ghcr.io/rust-cross/manylinux_2_28-cross:armv7
ppc64le	2014/2_17	ghcr.io/rust-cross/manylinux2014-cross:ppc64le
ppc64le	2_24	messense/manylinux_2_24-cross:ppc64le	Deprecated
ppc64le	2_28	ghcr.io/rust-cross/manylinux_2_28-cross:ppc64le
ppc64	2014/2_17	ghcr.io/rust-cross/manylinux2014-cross:ppc64
s390x	2014/2_17	ghcr.io/rust-cross/manylinux2014-cross:s390x
s390x	2_24	messense/manylinux_2_24-cross:s390x	Deprecated
s390x	2_28	ghcr.io/rust-cross/manylinux_2_28-cross:s390x
riscv64	2_31	ghcr.io/rust-cross/manylinux_2_31-cross:riscv64
riscv64	2_39	quay.io/pypa/manylinux_2_39_riscv64:latest
loongarch64	2_36	ghcr.io/rust-cross/manylinux_2_36-cross:loongarch64

You can override it by supplying the container input. Note that if use official manylinux docker images for platforms other than x86_64 and i686, you will need to setup QEMU before using this action, for example

- name: Setup QEMU
  uses: docker/setup-qemu-action@v1
- uses: PyO3/maturin-action@v1
  with:
    command: build
    args: --release

Note that the actions/setup-python action won't affect manylinux build since it's containerized, so if you want to build for certain Python version for Linux, use -i pythonX.Y in the args option in PyO3/maturin-action instead, for example

- uses: PyO3/maturin-action@v1
  with:
    args: --release -i python3.10

To build for every available interpreter at once — including the free-threaded builds — use --find-interpreter; see Free-threaded CPython below.

Free-threaded CPython

maturin builds wheels for the free-threaded ("no-GIL") CPython builds automatically when you pass --find-interpreter and a free-threaded interpreter is available. Free-threaded interpreters carry a t suffix (python3.14t, python3.15t, …); maturin discovers the officially supported ones (CPython 3.14 and newer) the same way it discovers the regular builds — the experimental 3.13t is not discovered automatically. Discovery needs a reasonably recent maturin, which the action installs by default.

Linux (manylinux)

No configuration needed — the default manylinux containers ship the free-threaded interpreters, and the action puts every interpreter under /opt/python on PATH, so --find-interpreter finds them:

- uses: PyO3/maturin-action@v1
  with:
    command: build
    args: --release --find-interpreter

macOS, Windows, and non-manylinux Linux (`manylinux: off`)

These run on the host, so the interpreters come from your own actions/setup-python step. Install the free-threaded build alongside the regular one:

- uses: actions/setup-python@v6
  with:
    python-version: |
      3.14
      3.14t
- uses: PyO3/maturin-action@v1
  with:
    command: build
    args: --release --find-interpreter

setup-python exposes the free-threaded build under its t-suffixed name (python3.14t, or python3.14t.exe on Windows), which is what --find-interpreter looks for.

Windows: build the regular and free-threaded interpreters in separate jobs

On Windows, co-installing the regular and free-threaded interpreters of the same minor version in one setup-python step can fail (python/cpython#127294, #313). Use a matrix with one interpreter per job instead.

Stable ABI (abi3 / abi3t)

The free-threaded build has its own stable ABI, abi3t (PEP 803, added in CPython 3.15), distinct from the GIL-enabled abi3. PyO3 exposes both as Cargo features, and projects can enable both when they want stable ABI wheels by default:

pyo3 = { version = "0.29", features = ["abi3-py310", "abi3t-py315"] }

One maturin invocation selects at most one stable ABI family, so do not expect one --find-interpreter build to emit both forward-compatible wheels. To publish a complete wheel set for current non-EOL CPython releases, run separate maturin builds with different interpreters. The same default Cargo features can be used for each build:

- name: Build abi3 wheel
  uses: PyO3/maturin-action@v1
  with:
    args: --release -i python3.10

- name: Build CPython 3.14t wheel
  uses: PyO3/maturin-action@v1
  with:
    args: --release -i python3.14t

- name: Build abi3t wheel
  uses: PyO3/maturin-action@v1
  with:
    args: --release -i python3.15t

The abi3-py310 wheel supports GIL-enabled CPython 3.10 and newer. The abi3t-py315 wheel supports CPython 3.15 and newer, both GIL-enabled and free-threaded. Free-threaded CPython 3.14 predates abi3t, so the python3.14t build produces the version-specific cp314-cp314t wheel.

If stable ABI support is behind a project feature, pass that feature to both builds. If a project enables only abi3 (no abi3t), --find-interpreter builds no free-threaded stable ABI wheel; request a version-specific free-threaded wheel explicitly with, e.g., -i python3.14t.

Hardening Release pipelines

We recommend the following steps for hardening release pipelines:

When targeting PyPI, set --compatibility pypi to activate its pre-upload check
Set an explicit manylinux: version for each target to prevent silent regressions
Pin both maturin-action and maturin version, and use a service such as renovate to update them

strategy:
  matrix:
    platform:
      - target: aarch64-unknown-linux-gnu
        arch: aarch64
        manylinux: 2_28
      - target: armv7-unknown-linux-gnueabihf
        arch: armv7
        manylinux: 2_17

steps:
  # [...]
  - name: "Build wheels"
    uses: PyO3/maturin-action@86b9d133d34bc1b40018696f782949dac11bd380 # v1.49.4
    with:
      maturin-version: v1.11.5
      target: ${{ matrix.platform.target }}
      manylinux: ${{ matrix.platform.manylinux }}
      args: --release --locked --compatibility pypi

An example renovate configuration

// Maturin version used in maturin-action
{
  customType: "regex",
  managerFilePatterns: ["/.github/workflows/.*\\.yml$/"],
  matchStrings: ["maturin-version: (?<currentValue>v\\d+\\.\\d+\\.\\d+)"],
  depNameTemplate: "maturin",
  packageNameTemplate: "PyO3/maturin",
  datasourceTemplate: "github-releases",
},

Contributing

To build after code changes:

npm run all

License

This work is released under the MIT license. A copy of the license is provided in the LICENSE file.