Modify the handing of Frameworks on Apple platforms #5606

freakboy3742 · 2025-11-06T07:14:45Z

On Apple platforms, Python is often provided as a framework build, rather than a dynamic library. This requires different linking commands if libPython is to be linked with a binary module.

With this change, if linking against libPython is enabled, and the sysconfigdata for the platform provides a value for PYTHONFRAMEWORK, the linking step will now performed against the framework (the equivalent of passing -framework to the C compiler, or the rustc-link-lib=framework=$PYTHONFRAMEWORK), with a framework search path defined by PYTHONFRAMEWORKPREFIX (the equivalent of -F, or rustc-link-search=framework=$PYTHONFRAMEWORKPREFIX).

freakboy3742 · 2025-11-06T08:46:45Z

@davidhewitt I did some digging looking for the appropriate place to document this, but it's not entirely clear to me what that would be. The only references to linking libPython that I could find were in the macOS section of building-and-distribution.md - but those seem related to "manual builds", and I'm not sure if that's the same thing here.

I'm not sure if that was what you were referring to about being able to deprecate regarding macOS? That includes reference to add_python_framework_link_args() - but in the context of macOS builds, I'm not sure how this would be turned on, since linking against the framework will be disabled on macOS.

Any pointers or assistance here would be appreciated.

It also took a couple of tries to fix some odd edge cases that didn't show up in local testing - an empty framework definition wasn't being handled consistently as "no framework" AFAICT, plus a linking error on Linux that I think I've handled correctly.

At present, when targeting an `abi3` build, Maturin will use a dummy interpreter to provide build configuration details, unless the user specifies an interpreter with `--interpreter`, or the target is cross-compiling, or Windows is being targeted. The use of a dummy interpreter when a real interpreter is available can lead to the interpreter details that are available and defined in `sysconfigdata` not being used as part of the build process. This was discovered in the process of working on iOS support (see #2827 and #2828); although the iOS build environment *does* provide build configuration details, those details were not being passed down to the PyO3 build configuration. With those two patches (and some patches to PyO3 - see PyO3/pyo3#5605 and PyO3/pyo3#5606), it was possible to build a non-abi3 wheel; but this patch was needed to build an abi3 wheel.

davidhewitt

Thanks for this, overall looks good to me, just a few small thoughts.

I'm not sure if that was what you were referring to about being able to deprecate regarding macOS? That includes reference to add_python_framework_link_args() - but in the context of macOS builds, I'm not sure how this would be turned on, since linking against the framework will be disabled on macOS.

add_python_framework_link_args() was indeed what I was thinking of, but having tested locally I think it's still necessary even with this PR.

davidhewitt · 2025-11-11T15:39:43Z

pyo3-build-config/src/impl_.rs

+    /// The name of the Python framework (if available)
+    ///
+    /// Serialized to `framework`.


I think we should note that if this is set, this will be used for linking instead of shared and lib_name.

davidhewitt · 2025-11-11T15:49:58Z

pyo3-build-config/src/impl_.rs

        let python_framework_prefix = sysconfigdata
            .get_value("PYTHONFRAMEWORKPREFIX")
            .map(str::to_string);


I wonder if we should do something similar to filter out cases where the prefix is an empty string? Maybe if that is semantically no different from None, we should consider removing the Option outer layer from these variables and just treat the empty string as unset?

I think I'd lean to filtering out empty PYTHONFRAMEWORKPREFIX examples; I can't speak with much Rust experience, but as a Python user, an explicit "None" makes more sense to me than ignoring an empty string. I'll push an update to that effect.

davidhewitt

Great, thanks for this!

davidhewitt · 2025-11-12T21:40:44Z

pyo3-ffi/build.rs

        "cargo:rustc-link-lib={link_model}{alias}{lib_name}",
-        link_model = if interpreter_config.shared {
+        link_model = if interpreter_config.framework.is_some() {
+            "framework="


I think the 3.11 CI failure has found a problem with this approach.

Seems like framework=Python does not specify the version, and nor does the search prefix which is just /Library/Frameworks (for the official distributions).

$ /Library/Frameworks/Python.framework/Versions/3.13/bin/python3 -m sysconfig | grep -i PYTHONFRAMEWORK PYTHONFRAMEWORK = "Python" PYTHONFRAMEWORKDIR = "Python.framework" PYTHONFRAMEWORKINSTALLDIR = "/Library/Frameworks/Python.framework" PYTHONFRAMEWORKINSTALLNAMEPREFIX = "/Library/Frameworks/Python.framework/Versions/3.13" PYTHONFRAMEWORKPREFIX = "/Library/Frameworks"

Not sure what implications this has for the iOS build either? Seems like it's fundamentally impossible to use frameworks and link the right version.

I wonder, maybe we don't need this PR? If cross-compile env has the correct lib_dir, potentially PyO3 main is now already doing the correct thing to link against iOS via the versioned .dylib directly with the other patches placed into PyO3 and maturin?

I think the 3.11 CI failure has found a problem with this approach.

Which failure is this? I'm seeing 11 skips, 32 successful tests in the most recent CI pass.

Seems like framework=Python does not specify the version, and nor does the search prefix which is just /Library/Frameworks (for the official distributions).

$ /Library/Frameworks/Python.framework/Versions/3.13/bin/python3 -m sysconfig | grep -i PYTHONFRAMEWORK PYTHONFRAMEWORK = "Python" PYTHONFRAMEWORKDIR = "Python.framework" PYTHONFRAMEWORKINSTALLDIR = "/Library/Frameworks/Python.framework" PYTHONFRAMEWORKINSTALLNAMEPREFIX = "/Library/Frameworks/Python.framework/Versions/3.13" PYTHONFRAMEWORKPREFIX = "/Library/Frameworks"

Not sure what implications this has for the iOS build either? Seems like it's fundamentally impossible to use frameworks and link the right version.

So - macOS frameworks and iOS frameworks (and every other non-macOS framework) are structured slightly differently.

macOS frameworks are versioned - there's a single top-level framework, with a "Versions" subfolder; each version of the framework is then contained in the top level framework. A Current symlink exists to point at one specific version, and the top level framework links the content of the current version so that /Library/Frameworks/Python.framework can be used for linking. However, that doesn't give you control over the specific version. If you want a specific version, you need to use -F /Library/Frameworks/Python.framework/Versions/3.13 as your framework search path.

I wonder, maybe we don't need this PR? If cross-compile env has the correct lib_dir, potentially PyO3 main is now already doing the correct thing to link against iOS with the other patches placed into PyO3 and maturin?

So... that doesn't currently work, because iOS doesn't ship a copy of libPython*.dylib in the lib folder. There's a range of reasons why that is the case... but with some other accomodations, that might indeed be an easier way to solve the problem. I'll experiment with this and report back.

In the merge queue https://github.com/PyO3/pyo3/actions/runs/19310395011/job/55228919449

you need to use -F /Library/Frameworks/Python.framework/Versions/3.13 as your framework search path.

I think I attempted this yesterday and had no luck. Possibly because Python.Framework only exists in /Library/Frameworks and not in any of the versioned subdirectories?

I added CI-build-full label to this PR so any further pushes will run the full suite of versions we run in the merge queue.

freakboy3742 · 2025-11-18T06:31:18Z

I've experimented, and you're correct - if we put a lib folder in the support package, using the same "symlink to framework binary" approach as is used by macOS, this patch is no longer required. With a patched copy of the iOS support package that includes the lib folder, I've been able to use the current PyO3 and Maturin mainline branches to build binaries of cryptography

I've submitted this fix upstream; it will take a while to propegate that change to all the places where it needs to exist, but on a similar sort of timeframe that you suggested for a new PyO3 release.

On that basis, I'm going to close this PR.

davidhewitt · 2025-11-18T09:54:43Z

Ok, that suits me! 😄

freakboy3742 added 8 commits November 6, 2025 15:09

Modify handling of Python Framework linking.

cf315b3

Add news fragment.

9f0aac5

Correct rustfmt issues.

5fc325b

Correct some problems identified by clippy.

3820fa3

Interpret an empty PYTHONFRAMEWORK as None not an empty string.

ca120b7

Corrected handling of empty PYTHONFRAMEWORK definitions.

55a1d95

Only add a framework linking path if there's a framework.

4ed808d

Cleanup rustfmt problems.

4a77d15

freakboy3742 mentioned this pull request Nov 7, 2025

If an interpreter is available, use it, even when building ABI3. PyO3/maturin#2829

Merged

davidhewitt reviewed Nov 11, 2025

View reviewed changes

freakboy3742 added 3 commits November 12, 2025 08:32

Merge branch 'main' into framework-linking

4bc523d

Document framework linking behavior.

20d4cb3

Convert empty framework prefixes to None.

f2260c0

davidhewitt approved these changes Nov 12, 2025

View reviewed changes

davidhewitt added this pull request to the merge queue Nov 12, 2025

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Nov 12, 2025

davidhewitt requested changes Nov 12, 2025

View reviewed changes

davidhewitt added the CI-build-full label Nov 13, 2025

freakboy3742 mentioned this pull request Nov 18, 2025

Add dylib symlink to iOS XCframework python/cpython#141692

Closed

freakboy3742 closed this Nov 18, 2025

freakboy3742 deleted the framework-linking branch November 18, 2025 06:31

Modify the handing of Frameworks on Apple platforms #5606

Modify the handing of Frameworks on Apple platforms #5606

Uh oh!

Conversation

freakboy3742 commented Nov 6, 2025

Uh oh!

freakboy3742 commented Nov 6, 2025

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

davidhewitt Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

freakboy3742 Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

davidhewitt Nov 12, 2025 • 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!

freakboy3742 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

freakboy3742 commented Nov 18, 2025

Uh oh!

davidhewitt commented Nov 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

davidhewitt Nov 12, 2025 •

edited

Loading