Update/Add free-threaded CPython framework (macOS)

[giampaolo]

Tool name

CPython free-threaded framework (PythonTFramework)

Tool license

PSF

Add or update?

• Add
• Update

Desired version

3.14

Approximate size

~100 MB on disk (same .pkg, extra framework)

Brief description of tool

The images ship CPython as a framework, registered with pkgutil as org.python.Python.PythonFramework-3.14. The free-threaded variant, PythonTFramework-3.14, is not registered.

Both live in the same python.org .pkg. The free-threaded one is just a non-default choice, enabled with -applyChoiceChangesXML. So the image already installs the package that contains it.

cibuildwheel skips the install when the receipt is there, so a normal 3.14 build costs 0s. A free-threaded build re-runs the same installer to flip that one choice:

+ sudo installer -pkg python-3.14.6-macos11.pkg -applyChoiceChangesXML ... -target /
installer: Upgrading at base path /
installer: The upgrade was successful.

Note "Upgrading": the package is already installed.

That costs 63.5s on macos-15-intel and 38.7s on macos-15 arm64, every job, every run. It hits anyone publishing free-threaded macOS wheels.

URL for tool's homepage

https://www.python.org/downloads/macos/

Provide a basic test case to validate the tool's functionality.

  pkgutil --pkgs | grep PythonTFramework
  /Library/Frameworks/PythonT.framework/Versions/3.14/bin/python3.14t -VV
  /Library/Frameworks/PythonT.framework/Versions/3.14/bin/python3.14t -c \
      "import sys; assert not sys._is_gil_enabled()"

Platforms where you need the tool

• Azure DevOps
• [ x ] GitHub Actions

Runner images where you need the tool

• Ubuntu 22.04
• Ubuntu 22.04 Arm64
• Ubuntu 24.04
• Ubuntu 24.04 Arm64
• Ubuntu 26.04
• Ubuntu 26.04 Arm64
• Ubuntu Slim
• [ x ] macOS 14
• [ x ] macOS 14 Arm64
• [ x ] macOS 15
• [ x ] macOS 15 Arm64
• [ x ] macOS 26
• [ x ] macOS 26 Arm64
• Windows Server 2022
• Windows Server 2025
• Windows Server 2025 with Visual Studio 2026
• Windows Desktop 11
• Windows Desktop 11 with Visual Studio 2026

Can this tool be installed during the build?

Yes. Same .pkg that already installs CPython, run with the choice XML that enables the free-threaded framework.

[giampaolo]

Just enable it on the image, not as default. Making it default would repoint python3 at a free-threaded interpreter and break everything else. Tools call /Library/Frameworks/PythonT.framework/Versions/3.14/bin/python3.14t by absolute path, so nothing about interpreter resolution needs to change.

The image already installs the .pkg containing both frameworks, just not the free-threaded choice, so only the regular one gets a pkgutil receipt. Installing that choice too (via -applyChoiceChangesXML) is all that's needed.

Cost today, both halves of the same job, same .pkg, on macos-15-intel (log) is:

Installing Python cp314...
+ pkgutil --pkgs
                                                           ✓ 0.02s

Installing Python cp314t...
+ pkgutil --pkgs
+ Download python-3.14.6-macos11.pkg
+ sudo installer -pkg ... -applyChoiceChangesXML free-threaded-enable-314.xml
installer: The upgrade was successful.        <- 93 seconds later

Same code path, the only difference is whether the receipt exists. The download is cached and takes a second; the 93s is installer unpacking a framework the image already shipped.

[v-GeorgyPuzakov]

Hi @giampaolo,
We will discuss this with the team and get back to you.