manylinux rust/pyo3 build guide

$ maturin build --release
💥 maturin failed
  Caused by: Error ensuring manylinux_2_17 compliance
  Caused by: Your library is not manylinux_2_17 (aka manylinux2014) compliant
  because of the presence of too-recent versioned symbols:
  ["libc.so.6 offending versions: GLIBC_2.18, GLIBC_2.25, GLIBC_2.28, GLIBC_2.29, GLIBC_2.33, GLIBC_2.34",
   "libm.so.6 offending versions: GLIBC_2.29"]

# build manylinux-compliant wheels using docker
docker run --rm \
    -v "$(pwd)":/io \
    -w /io \
    ghcr.io/pyo3/maturin:latest \
    build --release \
    --strip \
    --manylinux 2_28 \
    -o dist

# for specific python versions
docker run --rm \
    -v "$(pwd)":/io \
    -w /io \
    ghcr.io/pyo3/maturin:latest \
    build --release \
    --strip \
    --manylinux 2_28 \
    --interpreter python3.11 python3.12 \
    -o dist

# install zig support
pip install maturin[zig]

# build with zig targeting manylinux2014
maturin build --release --zig --manylinux 2_17

# target specific glibc version
maturin build --release --zig --manylinux 2_28

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  linux:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        target: [x86_64, aarch64]
    steps:
      - uses: actions/checkout@v4
      - uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.target }}
          manylinux: auto # automatically selects appropriate version
          command: build
          args: --release --strip
      - name: Upload wheels
        uses: actions/upload-artifact@v4
        with:
          name: wheels-linux-${{ matrix.target }}
          path: dist

ImportError: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.18' not found

# option 1: build in docker
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin:latest build --release

# option 2: skip auditwheel (not for pypi)
maturin build --release --auditwheel skip

# option 3: use zig
maturin build --release --zig --manylinux 2_17

Your library is not manylinux_2_17 compliant because of the presence of
too-recent versioned symbols

ERROR: package-0.1.0-cp311-cp311-linux_x86_64.whl is not a supported wheel on this platform.

undefined reference to `_Py_Dealloc'
undefined reference to `_Py_NoneStruct'

# Cargo.toml
[dependencies.pyo3]
version = "0.24"
features = ["extension-module", "abi3-py311"]  # abi3 for forward compatibility

[lib]
name = "your_module"
crate-type = ["cdylib"]

export MATURIN_PYPI_TOKEN="pypi-YOUR_TOKEN_HERE"
maturin publish

# ~/.pypirc
[pypi]
username = __token__
password = pypi-YOUR_TOKEN_HERE

#!/bin/bash
# complete publishing workflow

# 1. build wheels in docker
docker run --rm -v "$(pwd)":/io -w /io \
    ghcr.io/pyo3/maturin:latest \
    build --release --strip --manylinux 2_28 -o dist

# 2. test locally
pip install dist/*.whl
python -c "import your_module; print(your_module.__version__)"

# 3. upload to testpypi first
export MATURIN_PYPI_TOKEN="pypi-test-YOUR_TEST_TOKEN"
maturin upload --repository testpypi dist/*.whl

# 4. test from testpypi
pip install -i https://test.pypi.org/simple/ your-package

# 5. upload to production pypi
export MATURIN_PYPI_TOKEN="pypi-YOUR_PRODUCTION_TOKEN"
maturin upload dist/*.whl

# check system glibc version
ldd --version

# inspect wheel metadata
unzip -l dist/*.whl | grep WHEEL
python -m zipfile -l dist/*.whl

# check wheel compliance
auditwheel show dist/*.whl

# verify glibc symbol versions (critical for debugging)
objdump -T target/release/lib*.so | grep GLIBC | sort -u

# example output showing problematic symbols:
# 0000000000000000 DF *UND* 0000000000000000 (GLIBC_2.29) log
# 0000000000000000 DF *UND* 0000000000000000 (GLIBC_2.34) pthread_key_create
# these symbols would prevent running on systems with glibc < 2.34

# create clean test environment
python -m venv test_env
source test_env/bin/activate

# install and test
pip install dist/*.whl
python -c "import your_module"

# check linked libraries
ldd test_env/lib/python*/site-packages/your_module*.so

# build universal2 wheel
maturin build --release --universal2

# or separate builds
maturin build --release --target x86_64-apple-darwin
maturin build --release --target aarch64-apple-darwin

- uses: PyO3/maturin-action@v1
  with:
    target: x86_64-pc-windows-msvc
    command: build
    args: --release

# using docker
docker run --rm \
    -v "$(pwd)":/io \
    -w /io \
    ghcr.io/pyo3/maturin:latest \
    build --release \
    --target aarch64-unknown-linux-gnu \
    --manylinux 2_28 \
    -o dist

# using zig
maturin build --release --zig \
    --target aarch64-unknown-linux-gnu \
    --manylinux 2_28

build fails with glibc error?
├── yes → build in manylinux docker container
│   ├── still fails? → check rust version >= 1.64
│   └── works → use this approach for ci/cd
└── no → different issue
    ├── linking errors? → check pyo3 features in cargo.toml
    ├── upload fails? → check pypi token configuration
    └── import fails? → verify wheel platform compatibility

#!/bin/bash
set -e

# default to manylinux_2_28 for broad compatibility
MANYLINUX_VERSION=${1:-2_28}

echo "building manylinux${MANYLINUX_VERSION} wheels..."

# clean previous builds
rm -rf dist/

# build wheels in docker
docker run --rm \
    -v "$(pwd)":/io \
    -w /io \
    ghcr.io/pyo3/maturin:latest \
    build --release \
    --strip \
    --manylinux ${MANYLINUX_VERSION} \
    -o dist

# verify wheel compliance
for wheel in dist/*.whl; do
    echo "checking: $wheel"
    docker run --rm \
        -v "$(pwd)":/io \
        -w /io \
        ghcr.io/pyo3/maturin:latest \
        auditwheel show "$wheel"
done

echo "wheels built successfully in dist/"
ls -la dist/