feat: re-implement delocate for repairing macOS wheels by messense · Pull Request #3114 · PyO3/maturin

messense · 2026-04-02T11:03:54Z

This PR implements native macOS wheel repair in maturin, providing the Rust equivalent of Python's delocate tool.

What it does

When building macOS wheels, maturin now automatically:

Audits Mach-O binaries for external .dylib dependencies
Bundles non-system libraries into a .dylibs/ directory inside the wheel
Rewrites install names to use @loader_path-relative references
Ad-hoc codesigns all modified binaries (required on Apple Silicon)

Key features

Universal2 support: Analyzes each architecture slice separately to discover arch-specific dependencies, then verifies bundled dylibs contain all required architecture slices
Smart dependency filtering: Skips system libraries (/usr/lib/, /System/), libpython, and Python.framework (including free-threaded PythonT.framework)
Transitive dependency handling: Only bundles libraries actually reachable from non-skipped dependencies
Cross-compilation support: Works with SDK sysroots (e.g., osxcross)
Pure-Rust signing: Uses arwen-codesign for cross-compilation scenarios; native codesign CLI on macOS

Implementation

MacOSRepairer implements the WheelRepairer trait introduced in refactor: introduce WheelRepairer trait #3112
Uses arwen crate for Mach-O install name/rpath manipulation

Add arwen = 0.0.5 (Mach-O patching) and arwen-codesign = 0.0.1-alpha.1 (pure Rust ad-hoc codesigning) as optional dependencies behind a new 'auditwheel' Cargo feature. Add 'auditwheel' to the 'full' feature list. These enable cross-platform wheel repair: - macOS: Mach-O install name rewriting and ad-hoc codesigning - Works from any host OS (pure Rust, no macOS tools needed)

Add src/auditwheel/macos.rs with MacOSRepairer that uses arwen for Mach-O install name/rpath manipulation and arwen-codesign for pure-Rust ad-hoc code signing. No macOS-only tool dependencies. Key behavior: - Filters system libraries (/usr/lib/*, /System/*) and libpython - Rewrites LC_LOAD_DYLIB to @loader_path-relative names - Sets LC_ID_DYLIB to /DLC/<libs_dir>/<name> (matching delocate) - Removes absolute rpaths, keeps @loader_path/@executable_path - Ad-hoc codesigns all modified binaries (cross-platform) - Uses .dylibs directory (matching delocate convention)

Update auditwheel/mod.rs to export MacOSRepairer (feature-gated behind 'auditwheel'). Wire it into make_repairer() in build_context/repair.rs so macOS builds use MacOSRepairer for wheel repair instead of returning None.

The is_libpython check now recognizes Python.framework paths in addition to traditional libpython3.*.dylib files. This fixes pyo3-bin bindings that link against /Library/Frameworks/Python.framework/Versions/X/Python. Also adds should_bundle_library() to properly error on missing non-system dependencies instead of silently skipping them.

arwen's MachoContainer caches parsed load command offsets, which become stale after modifications that change install name lengths. Re-parsing between each operation ensures correct offsets are used. This fixes corruption when changing install names to longer strings, which shifts subsequent load commands in the binary.

The is_libpython() check only recognized Python.framework but free-threaded Python builds (3.13t, 3.14t) use PythonT.framework. This caused the framework to be bundled and the binary patched to reference a non-existent hashed library name.

The pure-Rust arwen-codesign library requires an LC_CODE_SIGNATURE load command which older dylibs (e.g., Homebrew's libintl) don't have. Use Apple's codesign CLI directly on macOS for reliability, keeping the pure-Rust implementation for cross-compilation from other platforms.

Use reachability analysis to avoid bundling libraries that are only transitive dependencies of skipped libraries (e.g., libintl via Python.framework). Only bundle libs reachable from the artifact without going through a skipped library.

Copilot

Pull request overview

This PR adds a macOS wheel “repair” implementation (delocate equivalent) and wires it into the build flow under a new auditwheel feature, including ad-hoc Mach-O signing support.

Changes:

Introduce MacOSRepairer to audit/patch Mach-O wheels and bundle external .dylib dependencies.
Add a macos_sign helper module for ad-hoc signing on macOS (via codesign) and non-macOS (via arwen-codesign).
Add auditwheel Cargo feature + dependencies and enable it in the full feature set.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`src/build_context/repair.rs`	Enables selecting `MacOSRepairer` for macOS targets when `auditwheel` feature is on.
`src/auditwheel/mod.rs`	Adds macOS modules and re-exports `MacOSRepairer` behind `auditwheel` feature gating.
`src/auditwheel/macos_sign.rs`	New module implementing ad-hoc Mach-O signing for macOS/cross builds.
`src/auditwheel/macos.rs`	New `WheelRepairer` implementation for macOS (delocate-like audit/patch).
`Cargo.toml`	Adds optional deps (`arwen`, `arwen-codesign`) and introduces/enables `auditwheel` feature.

Extract reachable_libs() as a pure helper so the BFS reachability logic can be tested with synthetic dependency graphs. Add four test cases covering: skipped transitive deps, shared deps via non-skipped paths, transitive chains, and mid-chain skip blocking. Also document the /DLC/ synthetic install ID convention (matching Python's delocate tool).

…e positives

…ry sysroot-aware

…rification For universal2 builds, lddtree can only analyze one architecture slice at a time from a fat binary. This caused dependencies unique to one architecture to be missed during wheel repair. Changes: - Add thin_artifacts field to BuildArtifact storing per-arch (path, linked_paths) - MacOSRepairer::audit() now analyzes each thin binary separately, tracking which architectures require each library - Add AuditResult struct to cleanly return audit output including arch requirements - Add verify_universal_archs() using fat-macho to verify grafted dylibs contain all required architecture slices before patching - Clear error messages when a thin dylib is used but multiple archs need it This mirrors Python delocate's check_archs behavior - it assumes external dylibs on the build system are already fat/universal.

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 6 comments.

- Add bounds check for thin_artifacts count in universal2 audit - Fix rpath removal to only strip absolute paths (starts with '/') - Optimize patch_macho to use in-memory buffer, write once at end - Use archs.iter().cloned() instead of archs.clone() for efficiency - Add comprehensive tests for verify_universal_archs function

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 5 comments.

- Add ThinArtifact struct with arch, path, linked_paths fields - Remove index-based UNIVERSAL2_ARCHS mapping in macos.rs - Use HashSet for O(n) linked_paths deduplication instead of O(n²)

Copilot

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 3 comments.

messense added 4 commits April 2, 2026 19:02

feat: wire MacOSRepairer into build pipeline

fb8e26d

Update auditwheel/mod.rs to export MacOSRepairer (feature-gated behind 'auditwheel'). Wire it into make_repairer() in build_context/repair.rs so macOS builds use MacOSRepairer for wheel repair instead of returning None.

messense force-pushed the delocate branch from 0f23cbc to dd6d887 Compare April 2, 2026 12:05

messense added 2 commits April 2, 2026 20:48

messense force-pushed the delocate branch from f4698fa to 62d3ab4 Compare April 2, 2026 13:33

messense temporarily deployed to crates.io April 2, 2026 13:54 — with GitHub Actions Inactive

messense temporarily deployed to PyPI April 2, 2026 13:54 — with GitHub Actions Inactive

messense mentioned this pull request Apr 2, 2026

fix: support signing unsigned Mach-O binaries without LC_CODE_SIGNATURE nichmor/arwen#44

Merged

messense force-pushed the delocate branch 3 times, most recently from 17fa846 to 2c5abc0 Compare April 3, 2026 12:32

messense force-pushed the delocate branch from 2c5abc0 to 8760a3b Compare April 3, 2026 12:49

messense requested a review from Copilot April 3, 2026 13:24

Copilot AI reviewed Apr 3, 2026

View reviewed changes

Copilot started reviewing on behalf of messense April 3, 2026 13:39 View session

messense temporarily deployed to crates.io April 3, 2026 16:40 — with GitHub Actions Inactive

messense temporarily deployed to PyPI April 3, 2026 16:40 — with GitHub Actions Inactive

messense marked this pull request as ready for review April 4, 2026 00:16

messense added 2 commits April 4, 2026 08:28

fix(macos): use path-component matching in is_libpython to avoid fals…

a392764

…e positives

fix(macos): gate arwen-codesign to non-macOS and make is_system_libra…

33e87bd

…ry sysroot-aware

messense temporarily deployed to crates.io April 4, 2026 00:47 — with GitHub Actions Inactive

messense temporarily deployed to PyPI April 4, 2026 00:47 — with GitHub Actions Inactive

messense requested a review from Copilot April 4, 2026 02:00

messense linked an issue Apr 4, 2026 that may be closed by this pull request

Audit and repair macOS wheels support #1133

Closed

2 tasks

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Comment thread src/auditwheel/macos.rs Outdated

Comment thread src/auditwheel/macos.rs Outdated

Comment thread src/auditwheel/macos.rs

Comment thread src/build_context/repair.rs Outdated

Comment thread src/auditwheel/macos.rs

Comment thread src/auditwheel/macos_sign.rs

Copilot started reviewing on behalf of messense April 4, 2026 02:08 View session

messense temporarily deployed to crates.io April 4, 2026 02:21 — with GitHub Actions Inactive

messense temporarily deployed to PyPI April 4, 2026 02:21 — with GitHub Actions Inactive

messense requested a review from Copilot April 4, 2026 02:44

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Comment thread src/compile.rs

Comment thread src/compile.rs

Comment thread src/auditwheel/macos_sign.rs

Comment thread src/auditwheel/macos.rs

Comment thread Cargo.toml

Copilot started reviewing on behalf of messense April 4, 2026 02:59 View session

messense temporarily deployed to PyPI April 4, 2026 03:05 — with GitHub Actions Inactive

messense temporarily deployed to crates.io April 4, 2026 03:05 — with GitHub Actions Inactive

Refactor universal2 thin artifacts to use explicit arch field

22e3646

- Add ThinArtifact struct with arch, path, linked_paths fields - Remove index-based UNIVERSAL2_ARCHS mapping in macos.rs - Use HashSet for O(n) linked_paths deduplication instead of O(n²)

messense temporarily deployed to crates.io April 4, 2026 03:31 — with GitHub Actions Inactive

messense temporarily deployed to PyPI April 4, 2026 03:31 — with GitHub Actions Inactive

style: use type imports instead of inline std::collections::

dbf2513

messense deployed to crates.io April 4, 2026 05:50 — with GitHub Actions View deployment

messense deployed to PyPI April 4, 2026 05:50 — with GitHub Actions View deployment

messense requested a review from Copilot April 4, 2026 09:48

Copilot started reviewing on behalf of messense April 4, 2026 09:49 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Comment thread src/compile.rs

Comment thread src/auditwheel/macos.rs

Comment thread src/auditwheel/macos.rs

messense merged commit a8393eb into PyO3:main Apr 4, 2026
66 checks passed

messense deleted the delocate branch April 4, 2026 13:20

Uh oh!

Conversation

messense commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What it does

Key features

Implementation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

messense commented Apr 2, 2026 •

edited

Loading