Add support for delocating macOS wheels by charliermarsh · Pull Request #17336 · astral-sh/uv

charliermarsh · 2026-01-06T15:14:48Z

Summary

This PR adds support for delocating macOS wheels. The behavior is not yet exposed on the CLI; it's only intended for internal-to-uv use. The implementation is based on https://github.com/matthew-brett/delocate, specifically delocate-listdeps {wheel} to list library dependencies (exposed as list_wheel_dependencies()) and delocate-wheel --require-archs {delocate_archs} -w {dest_dir} {wheel} to copy external libraries into binaries (exposed as delocate_wheel()).

crates/uv-delocate/src/wheel.rs

crates/uv-delocate/src/macho.rs

crates/uv-delocate/src/error.rs

crates/uv-delocate/tests/integration_test.rs

crates/uv-configuration/src/target_triple.rs

crates/uv-delocate/src/delocate.rs

crates/uv-platform/src/macos.rs

crates/uv-delocate/src/delocate.rs

crates/uv-delocate/src/wheel.rs

konstin · 2026-01-13T13:30:08Z

crates/uv-static/src/env_vars.rs

+    /// Search path for dynamic libraries on macOS (checked before system paths).
+    ///
+    /// Used during wheel delocating to find library dependencies.
+    #[attr_added_in("0.9.22")]


Suggested change

#[attr_added_in("0.9.22")]

#[attr_added_in("next version")]

crates/uv-static/src/env_vars.rs

konstin · 2026-01-21T12:56:23Z

crates/uv-delocate/src/delocate.rs

+        // @loader_path and @executable_path are relative to the binary containing the reference.
+        let parent = binary_path.parent()?;
+        let resolved = parent.join(relative);
+        if let Ok(path) = resolved.canonicalize() {


What happens at runtime with a library like this, would this create a wheel with a shared library that fails to load?

konstin · 2026-01-21T15:00:02Z

crates/uv-delocate/src/delocate.rs

+
+        // Check macOS version compatibility against target version.
+        if let Some(version) = target_version {
+            check_macos_version_compatible(lib_path, version)?;


This and the find_max_macos_version below look off: In the Python delocate: there's a function that runs over the wheel directory after the libs have been copied and computes the minimum of all libs in the new wheel, I think that's libraries + binaries in our terminology (https://github.com/matthew-brett/delocate/blob/a97bc907ea5fab9256e2c92b995b332605fcd98b/delocate/delocating.py#L660-L691). It has the option to check for the required macos version support, but that check only runs if MACOSX_DEPLOYMENT_TARGET is set, otherwise it uses the minimum macos version possible with all binaries/libraries in the wheel. Do we have a test input wheel to check this?

konstin · 2026-01-21T15:23:20Z

crates/uv-delocate/src/macho.rs

+        new_name
+    );
+
+    let output = Command::new("install_name_tool")


More something for a follow-up PR, but where did we end up on using arwen to avoid the problems with subprocess calls? It's not tested enough rn, but were there any architectural concerns? mid-term, I rather fix bugs in a rust library than working around install_name_tool.

CC @geofft who has a way doing it without full arwen, avoiding rewriting the binary for just patching the relevant sections.

konstin · 2026-01-21T15:29:32Z

crates/uv-delocate/src/error.rs

+    PathNotInWheel { path: PathBuf, wheel_dir: PathBuf },
+
+    #[error("Unsupported Mach-O format: {0}")]
+    UnsupportedFormat(String),


This variant is unused

konstin · 2026-01-21T15:29:49Z

crates/uv-delocate/src/error.rs

+    MachOParse(String),
+
+    #[error("Dependency not found: {name} (required by {})", required_by.user_display())]
+    DependencyNotFound { name: String, required_by: PathBuf },


This variant is unused

konstin · 2026-01-21T15:31:08Z

crates/uv-delocate/src/lib.rs

+pub use delocate::{DelocateOptions, delocate_wheel, list_wheel_dependencies};
+pub use error::DelocateError;
+pub use macho::{Arch, MachOFile};
+pub use uv_platform::MacOSVersion;


Why is this external symbol pub-use?

konstin · 2026-01-21T15:56:23Z

crates/uv-delocate/tests/macos_version.rs

+}
+
+#[test]
+fn test_macos_version_ordering() {


I'm not sure if we need that test, it tests a #[derive(Ord)] in combination with the field order.

konstin · 2026-01-21T15:58:00Z

crates/uv-delocate/tests/wheel_operations.rs

+}
+
+#[test]
+fn test_find_dist_info() {


This now covered by the existing test suite

charliermarsh temporarily deployed to uv-test-registries January 6, 2026 15:16 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from afab653 to f593a05 Compare January 6, 2026 15:24

charliermarsh requested review from konstin and zanieb January 6, 2026 15:25

charliermarsh temporarily deployed to uv-test-registries January 6, 2026 15:26 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from f593a05 to f0e8c89 Compare January 6, 2026 15:30

charliermarsh temporarily deployed to uv-test-registries January 6, 2026 15:32 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from f0e8c89 to 55e7d53 Compare January 6, 2026 15:38

charliermarsh temporarily deployed to uv-test-registries January 6, 2026 15:40 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from 55e7d53 to 2fcfd67 Compare January 6, 2026 15:48

charliermarsh had a problem deploying to uv-test-registries January 6, 2026 15:51 — with GitHub Actions Error

charliermarsh force-pushed the charlie/delocate branch from 2fcfd67 to 5250e52 Compare January 6, 2026 15:52

charliermarsh temporarily deployed to uv-test-registries January 6, 2026 15:53 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from 5250e52 to 915cb56 Compare January 6, 2026 16:21

charliermarsh temporarily deployed to uv-test-registries January 6, 2026 16:23 — with GitHub Actions Inactive

charliermarsh marked this pull request as ready for review January 6, 2026 17:38

charliermarsh added the internal A refactor or improvement that is not user-facing label Jan 6, 2026

charliermarsh force-pushed the charlie/delocate branch 2 times, most recently from 49bf890 to fb8f82c Compare January 6, 2026 18:09

charliermarsh temporarily deployed to uv-test-registries January 6, 2026 18:11 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from fb8f82c to c7dddf2 Compare January 7, 2026 00:37

charliermarsh temporarily deployed to uv-test-registries January 7, 2026 00:40 — with GitHub Actions Inactive

konstin reviewed Jan 7, 2026

View reviewed changes

charliermarsh temporarily deployed to uv-test-registries January 7, 2026 14:44 — with GitHub Actions Inactive

charliermarsh temporarily deployed to uv-test-registries January 7, 2026 14:51 — with GitHub Actions Inactive

charliermarsh temporarily deployed to uv-test-registries January 7, 2026 15:02 — with GitHub Actions Inactive

charliermarsh temporarily deployed to uv-test-registries January 7, 2026 15:15 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from b3467e9 to 2ca2ec0 Compare January 7, 2026 15:18

charliermarsh temporarily deployed to uv-test-registries January 7, 2026 15:20 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from 2ca2ec0 to 16795a9 Compare January 7, 2026 15:23

charliermarsh temporarily deployed to uv-test-registries January 8, 2026 15:19 — with GitHub Actions Inactive

charliermarsh force-pushed the charlie/delocate branch from f545efc to 15c0925 Compare January 12, 2026 02:10

charliermarsh temporarily deployed to uv-test-registries January 12, 2026 02:12 — with GitHub Actions Inactive

konstin reviewed Jan 13, 2026

View reviewed changes

charliermarsh force-pushed the charlie/delocate branch from 15c0925 to 6781fa4 Compare January 15, 2026 18:49

charliermarsh marked this pull request as draft January 15, 2026 18:50

charliermarsh requested review from konstin and zanieb January 15, 2026 20:25

charliermarsh marked this pull request as ready for review January 15, 2026 20:25

charliermarsh force-pushed the charlie/delocate branch from cacc338 to d04253c Compare January 15, 2026 20:27

charliermarsh added 18 commits January 21, 2026 09:56

Add support for delocating macOS wheels

78f4dd2

Use peek_bytes

d67cd46

Review feedback

64db6db

Use fixed permissions

3048003

Use with_platform_tags

b663185

Reuse code from uv-install-wheel

5a2f0ce

De-duplicate MacOSVersion

1886587

Fix duplication

ef3919b

Avoid unknown

0c3ca5e

Remove options

69b0c34

Remove unwraps

8899ad8

Handle bare library names

d42e772

Add a test

e258d64

Use relative_to

64fda1b

Clarify path

017822b

Update WHEEL

a2291d1

Reuse dist-info

fd4a253

Redo tag test

76adaf0

charliermarsh force-pushed the charlie/delocate branch from d04253c to 76adaf0 Compare January 21, 2026 15:02

konstin reviewed Jan 21, 2026

View reviewed changes

Comments

Conversation

charliermarsh commented Jan 6, 2026

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

konstin Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

konstin Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

konstin Jan 21, 2026 •

edited

Loading

konstin Jan 23, 2026 •

edited

Loading