# Python Apple Support: Building Python XCFrameworks for Apple Platforms

> Python Apple Support packages CPython as Xcode-compatible XCFrameworks for macOS, iOS, tvOS, watchOS, and visionOS. It is intended for developers embedding Python in Apple applications, but it does not build binary wheels for application dependencies.

**beeware/Python-Apple-support** — A meta-package for building a version of Python that can be embedded into a macOS, iOS, tvOS or watchOS project.

- Repository: https://github.com/beeware/Python-Apple-support
- Stars: 1,371 · Forks: 209
- Language: Makefile
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/beeware-python-apple-support

## Why Python Apple Support exists for Xcode applications

Python Apple Support addresses a distribution problem that appears when a Python application must run inside an Apple platform application. A normal macOS Python installation is not sufficient for an iOS, tvOS, watchOS, or visionOS app because those platforms require platform-specific builds, frameworks, and supported application binary interfaces. This project turns CPython and selected prerequisites into an `Python.xcframework` that Xcode can incorporate into a project.

The repository is aimed at developers packaging Python code as part of an Apple application, not at developers who simply want a Python interpreter for command-line use on a Mac. Its packages contain the Python runtime and standard library, but the README explicitly separates that work from building binary wheels for third-party packages. The supported branch is therefore part of an application runtime pipeline, not a complete Python packaging solution.

The default branch builds Python 3.15 according to the README. Separate branches are listed for Python 3.11, 3.12, 3.13, and 3.14. The README's Python 3.14 branch link points to the Python 3.13 branch URL, so a developer selecting that version should verify the branch target in GitHub rather than relying on the link as printed. That documentation inconsistency is small but relevant when choosing the source for a release build.

## The download, patch, compile, and XCFramework pipeline

The Makefile drives a reproducible sequence rather than acting as a thin installer. It downloads source packages, applies compatibility patches, compiles selected prerequisites and CPython, and creates multi-platform framework artifacts. The README calls the result a fat binary, while the actual Xcode-facing package is an XCFramework containing architecture-specific slices.

The macOS path differs from the embedded Apple platform paths. According to the README, the macOS package re-bundles the official macOS binary, makes it relocatable, removes IDLE, Tkinter, and turtle, and applies the App Store compliance patch. The iOS, tvOS, watchOS, and visionOS builds use the official PEP 730 iOS support code in Python 3.13, with relevant patches backported to Python 3.11 and 3.12. Additional patches add the other Apple platforms.

The repository's `Makefile` identifies `OS_LIST=macOS iOS tvOS watchOS visionOS` and sets a minimum version of 11.0 for macOS and 13.0 for iOS. The repository also defines target triples for Intel and Apple Silicon macOS builds, Intel and Apple Silicon simulators, and arm64 devices. This is source-level build infrastructure. The resulting `.tar.gz` archives are placed in `dist`, and each support package includes `VERSIONS` plus `Python.xcframework`.

## Building the 3.15 Apple platform packages

The repository documents no package-manager installation command for the meta-package. The practical source workflow is to clone or download the repository, change into its root directory, and invoke one of the documented Make targets. The build requires the Apple toolchain and the build steps performed by the repository; the README does not provide separate dependency-installation commands.

The following command builds every configured Apple platform package. Expect the process to download source archives, apply patches, compile the runtime, and write `.tar.gz` files to `dist`.

```bash
make
```

For a narrower build, select one documented platform target. For example, this command builds only the iOS package:

```bash
make iOS
```

The other documented targets are `macOS`, `tvOS`, `watchOS`, and `visionOS`. The Makefile also documents `all` as equivalent to the default build target. These commands do not create an application or an Xcode workspace by themselves. They produce framework archives that must then be added to an Apple project, with `USAGE.md` providing the detailed integration instructions.

## What Python.xcframework contains on each Apple platform

For macOS, the framework combines the supported macOS architectures identified by the Makefile: `macosx.x86_64` and `macosx.arm64`. This supports Intel Macs and Apple Silicon Macs, subject to the README's stated minimum of macOS 11, or Big Sur.

The embedded platform packages carry separate slices for devices and simulators. The README states that iOS supports `x86_64` and `arm64` simulators, while devices use `arm64`. WatchOS device support is listed as `arm64_32`, and visionOS uses `arm64` for devices. The README says visionOS does not officially support `x86_64` simulators. These distinctions matter because Xcode must select a slice matching both the destination device and the build architecture.

On iOS, tvOS, watchOS, and visionOS, the slice directory can serve as `PYTHONHOME` because it contains `bin`, `include`, and `lib`. The `bin` directory does not contain an invokable Python executable. It does contain shell aliases for compilers required by packaging tools, because Xcode uses `xcrun` dynamically while some C tooling expects `CC` not to contain spaces. The absence of an executable is intentional for these embedded platforms, not evidence of an incomplete runtime.

## Cross-platform packaging environments and test projects

Each embedded-platform slice includes a `platform-config` directory with subdirectories for supported architectures. The repository provides two documented mechanisms for making a macOS build environment behave as if it were targeting an embedded Apple platform.

The first mechanism is a `sitecustomize.py` script. If the relevant `platform-config` directory is placed on `PYTHONPATH`, startup customization patches methods in `sys`, `sysconfig`, and `platform` that otherwise identify the host as macOS. This is useful when a packaging tool must inspect target-platform characteristics.

The second mechanism is `make_cross_venv.py`. Calling it with the location of a virtual environment adds files to that environment's `site-packages`, applying the same patches when the environment is activated. The README also states that when `build` creates an isolated PEP 517 environment for a wheel, these patches are applied to that isolated environment. This arrangement changes environment detection for packaging, but it does not make macOS executables runnable on an Apple device.

For iOS and visionOS, distributions include a copy of the platform `testbed` Xcode project. The README points to the CPython documentation for testing packages with that project. The repository does not claim that a successful wheel build is an end-to-end application test.

## Why binary wheels remain outside the runtime package

The clearest boundary is between packaging Python itself and packaging third-party dependencies. Python Apple Support packages the Python standard library as platform binaries that can be loaded at runtime. The README says it does not address building binary wheels. It directs developers to PyPI for existing macOS binary wheels and to `cibuildwheel` when they need to build macOS wheels.

This distinction prevents a common adoption error. Installing `Python.xcframework` into Xcode supplies the interpreter and its standard library, but it does not guarantee that packages containing C or platform-specific extensions are available for every destination. An application team may still need per-architecture or per-platform wheels for dependencies, plus a method to place those wheels where the embedded interpreter can import them.

The cross-compilation environment scripts help tools identify the target platform and participate in isolated wheel builds. They do not remove the need to produce compatible wheel artifacts. The README also does not document a rollback procedure, runtime signing checklist, or complete dependency policy for application packages. Those points must be handled by the surrounding Xcode and application packaging workflow.

## Maintenance, releases, and MIT licensing

The repository is not archived. Its last push was on 2026-10-12, and the release list includes `3.15-b1` dated 2026-10-12, `3.14-b12` dated 2026-10-06, and `3.13-b16` dated 2026-10-06. This indicates recent source activity, but the README states that versioned packages live on separate branches, so adopting a team should also account for the maintenance policy of the selected Python branch rather than relying only on the default branch.

The repository uses the MIT license. That permits use, modification, distribution, and sublicensing subject to the license terms, but the README does not define a separate policy for redistributed CPython, OpenSSL, or other prerequisite licenses. Application distributors should inspect the license files for the exact source and binary components included in the generated archive. This is a licensing inventory task, not a conclusion that all redistributed components use the same terms.

Upgrade cost is tied to the selected branch. The Makefile contains version values for CPython and dependencies, while each support archive includes `VERSIONS` describing the code used. A branch change can therefore alter compiler inputs, patch sets, platform slices, and application packaging behavior. Comparing `VERSIONS` between releases gives maintainers a concrete way to identify what changed before rebuilding.

## Conclusion

Application teams that need a relocatable Python runtime inside an Apple platform project should consider the matching release branch, while developers who only need PyPI wheels should use existing wheel tooling instead. Before adoption, verify that a release contains the required Python branch, architecture slice, minimum OS version, and Xcode integration steps documented in USAGE.md.

## FAQ

### What platforms can Python Apple Support build for?

It can build Python packages for macOS, iOS, tvOS, watchOS, and visionOS. Each platform is selected through its corresponding Make target.

### Does Python Apple Support build binary wheels for my dependencies?

No. It packages the Python standard library but does not address building binary wheels. The README points to PyPI for existing macOS wheels and `cibuildwheel` for building them.

### How do I add Python to an Xcode project?

Briefcase can download the pre-compiled support packages and add them to an Xcode project, or a framework can be downloaded from the GitHub releases page and added manually. For detailed integration, the README directs developers to `USAGE.md`.

## Sources

- [beeware/Python-Apple-support on GitHub](https://github.com/beeware/Python-Apple-support)
- [Issues](https://github.com/beeware/Python-Apple-support/issues)
- [License: MIT](https://github.com/beeware/Python-Apple-support/blob/main/LICENSE)
- [README](https://github.com/beeware/Python-Apple-support/blob/main/README.md)
- [Releases](https://github.com/beeware/Python-Apple-support/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/beeware-python-apple-support