| 1 |
.. _using-ios: |
| 2 |
|
| 3 |
=================== |
| 4 |
Using Python on iOS |
| 5 |
=================== |
| 6 |
|
| 7 |
:Authors: |
| 8 |
Russell Keith-Magee (2024-03) |
| 9 |
|
| 10 |
Python on iOS is unlike Python on desktop platforms. On a desktop platform, |
| 11 |
Python is generally installed as a system resource that can be used by any user |
| 12 |
of that computer. Users then interact with Python by running a :program:`python` |
| 13 |
executable and entering commands at an interactive prompt, or by running a |
| 14 |
Python script. |
| 15 |
|
| 16 |
On iOS, there is no concept of installing as a system resource. The only unit |
| 17 |
of software distribution is an "app". There is also no console where you could |
| 18 |
run a :program:`python` executable, or interact with a Python REPL. |
| 19 |
|
| 20 |
As a result, the only way you can use Python on iOS is in embedded mode - that |
| 21 |
is, by writing a native iOS application, and embedding a Python interpreter |
| 22 |
using ``libPython``, and invoking Python code using the :ref:`Python embedding |
| 23 |
API <embedding>`. The full Python interpreter, the standard library, and all |
| 24 |
your Python code is then packaged as a standalone bundle that can be |
| 25 |
distributed via the iOS App Store. |
| 26 |
|
| 27 |
If you're looking to experiment for the first time with writing an iOS app in |
| 28 |
Python, projects such as `BeeWare <https://beeware.org>`__ and `Kivy |
| 29 |
<https://kivy.org>`__ will provide a much more approachable user experience. |
| 30 |
These projects manage the complexities associated with getting an iOS project |
| 31 |
running, so you only need to deal with the Python code itself. |
| 32 |
|
| 33 |
Python at runtime on iOS |
| 34 |
======================== |
| 35 |
|
| 36 |
iOS version compatibility |
| 37 |
------------------------- |
| 38 |
|
| 39 |
The minimum supported iOS version is specified at compile time, using the |
| 40 |
:option:`--host` option to ``configure``. By default, when compiled for iOS, |
| 41 |
Python will be compiled with a minimum supported iOS version of 13.0. To use a |
| 42 |
different minimum iOS version, provide the version number as part of the |
| 43 |
:option:`!--host` argument - for example, |
| 44 |
``--host=arm64-apple-ios15.4-simulator`` would compile an ARM64 simulator build |
| 45 |
with a deployment target of 15.4. |
| 46 |
|
| 47 |
Platform identification |
| 48 |
----------------------- |
| 49 |
|
| 50 |
When executing on iOS, ``sys.platform`` will report as ``ios``. This value will |
| 51 |
be returned on an iPhone or iPad, regardless of whether the app is running on |
| 52 |
the simulator or a physical device. |
| 53 |
|
| 54 |
Information about the specific runtime environment, including the iOS version, |
| 55 |
device model, and whether the device is a simulator, can be obtained using |
| 56 |
:func:`platform.ios_ver`. :func:`platform.system` will report ``iOS`` or |
| 57 |
``iPadOS``, depending on the device. |
| 58 |
|
| 59 |
:func:`os.uname` reports kernel-level details; it will report a name of |
| 60 |
``Darwin``. |
| 61 |
|
| 62 |
Standard library availability |
| 63 |
----------------------------- |
| 64 |
|
| 65 |
The Python standard library has some notable omissions and restrictions on |
| 66 |
iOS. See the :ref:`API availability guide for iOS <mobile-availability>` for |
| 67 |
details. |
| 68 |
|
| 69 |
Binary extension modules |
| 70 |
------------------------ |
| 71 |
|
| 72 |
One notable difference about iOS as a platform is that App Store distribution |
| 73 |
imposes hard requirements on the packaging of an application. One of these |
| 74 |
requirements governs how binary extension modules are distributed. |
| 75 |
|
| 76 |
The iOS App Store requires that *all* binary modules in an iOS app must be |
| 77 |
dynamic libraries, contained in a framework with appropriate metadata, stored |
| 78 |
in the ``Frameworks`` folder of the packaged app. There can be only a single |
| 79 |
binary per framework, and there can be no executable binary material outside |
| 80 |
the ``Frameworks`` folder. |
| 81 |
|
| 82 |
This conflicts with the usual Python approach for distributing binaries, which |
| 83 |
allows a binary extension module to be loaded from any location on |
| 84 |
``sys.path``. To ensure compliance with App Store policies, an iOS project must |
| 85 |
post-process any Python packages, converting ``.so`` binary modules into |
| 86 |
individual standalone frameworks with appropriate metadata and signing. For |
| 87 |
details on how to perform this post-processing, see the guide for :ref:`adding |
| 88 |
Python to your project <adding-ios>`. |
| 89 |
|
| 90 |
To help Python discover binaries in their new location, the original ``.so`` |
| 91 |
file on ``sys.path`` is replaced with a ``.fwork`` file. This file is a text |
| 92 |
file containing the location of the framework binary, relative to the app |
| 93 |
bundle. To allow the framework to resolve back to the original location, the |
| 94 |
framework must contain a ``.origin`` file that contains the location of the |
| 95 |
``.fwork`` file, relative to the app bundle. |
| 96 |
|
| 97 |
For example, consider the case of an import ``from foo.bar import _whiz``, |
| 98 |
where ``_whiz`` is implemented with the binary module |
| 99 |
``sources/foo/bar/_whiz.abi3.so``, with ``sources`` being the location |
| 100 |
registered on ``sys.path``, relative to the application bundle. This module |
| 101 |
*must* be distributed as ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz`` |
| 102 |
(creating the framework name from the full import path of the module), with an |
| 103 |
``Info.plist`` file in the ``.framework`` directory identifying the binary as a |
| 104 |
framework. The ``foo.bar._whiz`` module would be represented in the original |
| 105 |
location with a ``sources/foo/bar/_whiz.abi3.fwork`` marker file, containing |
| 106 |
the path ``Frameworks/foo.bar._whiz/foo.bar._whiz``. The framework would also |
| 107 |
contain ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin``, containing |
| 108 |
the path to the ``.fwork`` file. |
| 109 |
|
| 110 |
When running on iOS, the Python interpreter will install an |
| 111 |
:class:`~importlib.machinery.AppleFrameworkLoader` that is able to read and |
| 112 |
import ``.fwork`` files. Once imported, the ``__file__`` attribute of the |
| 113 |
binary module will report as the location of the ``.fwork`` file. However, the |
| 114 |
:class:`~importlib.machinery.ModuleSpec` for the loaded module will report the |
| 115 |
``origin`` as the location of the binary in the framework folder. |
| 116 |
|
| 117 |
Compiler stub binaries |
| 118 |
---------------------- |
| 119 |
|
| 120 |
Xcode doesn't expose explicit compilers for iOS; instead, it uses an ``xcrun`` |
| 121 |
script that resolves to a full compiler path (e.g., ``xcrun --sdk iphoneos |
| 122 |
clang`` to get the ``clang`` for an iPhone device). However, using this script |
| 123 |
poses two problems: |
| 124 |
|
| 125 |
* The output of ``xcrun`` includes paths that are machine specific, resulting |
| 126 |
in a sysconfig module that cannot be shared between users; and |
| 127 |
|
| 128 |
* It results in ``CC``/``CPP``/``LD``/``AR`` definitions that include spaces. |
| 129 |
There is a lot of C ecosystem tooling that assumes that you can split a |
| 130 |
command line at the first space to get the path to the compiler executable; |
| 131 |
this isn't the case when using ``xcrun``. |
| 132 |
|
| 133 |
To avoid these problems, Python provided stubs for these tools. These stubs are |
| 134 |
shell script wrappers around the underingly ``xcrun`` tools, distributed in a |
| 135 |
``bin`` folder distributed alongside the compiled iOS framework. These scripts |
| 136 |
are relocatable, and will always resolve to the appropriate local system paths. |
| 137 |
By including these scripts in the bin folder that accompanies a framework, the |
| 138 |
contents of the ``sysconfig`` module becomes useful for end-users to compile |
| 139 |
their own modules. When compiling third-party Python modules for iOS, you |
| 140 |
should ensure these stub binaries are on your path. |
| 141 |
|
| 142 |
Installing Python on iOS |
| 143 |
======================== |
| 144 |
|
| 145 |
Tools for building iOS apps |
| 146 |
--------------------------- |
| 147 |
|
| 148 |
Building for iOS requires the use of Apple's Xcode tooling. It is strongly |
| 149 |
recommended that you use the most recent stable release of Xcode. This will |
| 150 |
require the use of the most (or second-most) recently released macOS version, |
| 151 |
as Apple does not maintain Xcode for older macOS versions. The Xcode Command |
| 152 |
Line Tools are not sufficient for iOS development; you need a *full* Xcode |
| 153 |
install. |
| 154 |
|
| 155 |
If you want to run your code on the iOS simulator, you'll also need to install |
| 156 |
an iOS Simulator Platform. You should be prompted to select an iOS Simulator |
| 157 |
Platform when you first run Xcode. Alternatively, you can add an iOS Simulator |
| 158 |
Platform by selecting from the Platforms tab of the Xcode Settings panel. |
| 159 |
|
| 160 |
.. _adding-ios: |
| 161 |
|
| 162 |
Adding Python to an iOS project |
| 163 |
------------------------------- |
| 164 |
|
| 165 |
Python can be added to any iOS project, using either Swift or Objective C. The |
| 166 |
following examples will use Objective C; if you are using Swift, you may find a |
| 167 |
library like `PythonKit <https://github.com/pvieito/PythonKit>`__ to be |
| 168 |
helpful. |
| 169 |
|
| 170 |
To add Python to an iOS Xcode project: |
| 171 |
|
| 172 |
1. Build or obtain a Python ``XCFramework``. See the instructions in |
| 173 |
:source:`Apple/iOS/README.md` (in the CPython source distribution) for details on |
| 174 |
how to build a Python ``XCFramework``. At a minimum, you will need a build |
| 175 |
that supports ``arm64-apple-ios``, plus one of either |
| 176 |
``arm64-apple-ios-simulator`` or ``x86_64-apple-ios-simulator``. |
| 177 |
|
| 178 |
2. Drag the ``XCframework`` into your iOS project. In the following |
| 179 |
instructions, we'll assume you've dropped the ``XCframework`` into the root |
| 180 |
of your project; however, you can use any other location that you want by |
| 181 |
adjusting paths as needed. |
| 182 |
|
| 183 |
3. Add your application code as a folder in your Xcode project. In the |
| 184 |
following instructions, we'll assume that your user code is in a folder |
| 185 |
named ``app`` in the root of your project; you can use any other location by |
| 186 |
adjusting paths as needed. Ensure that this folder is associated with your |
| 187 |
app target. |
| 188 |
|
| 189 |
4. Select the app target by selecting the root node of your Xcode project, then |
| 190 |
the target name in the sidebar that appears. |
| 191 |
|
| 192 |
5. In the "General" settings, under "Frameworks, Libraries and Embedded |
| 193 |
Content", add ``Python.xcframework``, with "Embed & Sign" selected. |
| 194 |
|
| 195 |
6. In the "Build Settings" tab, modify the following: |
| 196 |
|
| 197 |
- Build Options |
| 198 |
|
| 199 |
* User Script Sandboxing: No |
| 200 |
* Enable Testability: Yes |
| 201 |
|
| 202 |
- Search Paths |
| 203 |
|
| 204 |
* Framework Search Paths: ``$(PROJECT_DIR)`` |
| 205 |
* Header Search Paths: ``"$(BUILT_PRODUCTS_DIR)/Python.framework/Headers"`` |
| 206 |
|
| 207 |
- Apple Clang - Warnings - All languages |
| 208 |
|
| 209 |
* Quoted Include In Framework Header: No |
| 210 |
|
| 211 |
7. Add a build step that processes the Python standard library, and your own |
| 212 |
Python binary dependencies. In the "Build Phases" tab, add a new "Run |
| 213 |
Script" build step *before* the "Embed Frameworks" step, but *after* the |
| 214 |
"Copy Bundle Resources" step. Name the step "Process Python libraries", |
| 215 |
disable the "Based on dependency analysis" checkbox, and set the script |
| 216 |
content to: |
| 217 |
|
| 218 |
.. code-block:: bash |
| 219 |
|
| 220 |
set -e |
| 221 |
source $PROJECT_DIR/Python.xcframework/build/build_utils.sh |
| 222 |
install_python Python.xcframework app |
| 223 |
|
| 224 |
If you have placed your XCframework somewhere other than the root of your |
| 225 |
project, modify the path to the first argument. |
| 226 |
|
| 227 |
8. Add Objective C code to initialize and use a Python interpreter in embedded |
| 228 |
mode. You should ensure that: |
| 229 |
|
| 230 |
* UTF-8 mode (:c:member:`PyPreConfig.utf8_mode`) is *enabled*; |
| 231 |
* Buffered stdio (:c:member:`PyConfig.buffered_stdio`) is *disabled*; |
| 232 |
* Writing bytecode (:c:member:`PyConfig.write_bytecode`) is *disabled*; |
| 233 |
* Signal handlers (:c:member:`PyConfig.install_signal_handlers`) are *enabled*; |
| 234 |
* System logging (:c:member:`PyConfig.use_system_logger`) is *enabled* |
| 235 |
(optional, but strongly recommended; this is enabled by default); |
| 236 |
* :envvar:`PYTHONHOME` for the interpreter is configured to point at the |
| 237 |
``python`` subfolder of your app's bundle; and |
| 238 |
* The :envvar:`PYTHONPATH` for the interpreter includes: |
| 239 |
|
| 240 |
- the ``python/lib/python3.X`` subfolder of your app's bundle, |
| 241 |
- the ``python/lib/python3.X/lib-dynload`` subfolder of your app's bundle, and |
| 242 |
- the ``app`` subfolder of your app's bundle |
| 243 |
|
| 244 |
Your app's bundle location can be determined using ``[[NSBundle mainBundle] |
| 245 |
resourcePath]``. |
| 246 |
|
| 247 |
Steps 7 and 8 of these instructions assume that you have a single folder of |
| 248 |
pure Python application code, named ``app``. If you have third-party binary |
| 249 |
modules in your app, some additional steps will be required: |
| 250 |
|
| 251 |
* You need to ensure that any folders containing third-party binaries are |
| 252 |
either associated with the app target, or are explicitly copied as part of |
| 253 |
step 7. Step 7 should also purge any binaries that are not appropriate for |
| 254 |
the platform a specific build is targeting (i.e., delete any device binaries |
| 255 |
if you're building an app targeting the simulator). |
| 256 |
|
| 257 |
* If you're using a separate folder for third-party packages, ensure that |
| 258 |
folder is added to the end of the call to ``install_python`` in step 7, and |
| 259 |
as part of the :envvar:`PYTHONPATH` configuration in step 8. |
| 260 |
|
| 261 |
* If any of the folders that contain third-party packages will contain ``.pth`` |
| 262 |
files, you should add that folder as a *site directory* (using |
| 263 |
:meth:`site.addsitedir`), rather than adding to :envvar:`PYTHONPATH` or |
| 264 |
:attr:`sys.path` directly. |
| 265 |
|
| 266 |
Testing a Python package |
| 267 |
------------------------ |
| 268 |
|
| 269 |
The CPython source tree contains :source:`a testbed project <Apple/iOS/testbed>` that |
| 270 |
is used to run the CPython test suite on the iOS simulator. This testbed can also |
| 271 |
be used as a testbed project for running your Python library's test suite on iOS. |
| 272 |
|
| 273 |
After building or obtaining an iOS XCFramework (see :source:`Apple/iOS/README.md` |
| 274 |
for details), create a clone of the Python iOS testbed project. If you used the |
| 275 |
``Apple`` build script to build the XCframework, you can run: |
| 276 |
|
| 277 |
.. code-block:: bash |
| 278 |
|
| 279 |
$ python cross-build/iOS/testbed clone --app <path/to/module1> --app <path/to/module2> app-testbed |
| 280 |
|
| 281 |
Or, if you've sourced your own XCframework, by running: |
| 282 |
|
| 283 |
.. code-block:: bash |
| 284 |
|
| 285 |
$ python Apple/testbed clone --platform iOS --framework <path/to/Python.xcframework> --app <path/to/module1> --app <path/to/module2> app-testbed |
| 286 |
|
| 287 |
Any folders specified with the ``--app`` flag will be copied into the cloned |
| 288 |
testbed project. The resulting testbed will be created in the ``app-testbed`` |
| 289 |
folder. In this example, the ``module1`` and ``module2`` would be importable |
| 290 |
modules at runtime. If your project has additional dependencies, they can be |
| 291 |
installed into the ``app-testbed/Testbed/app_packages`` folder (using ``pip |
| 292 |
install --target app-testbed/Testbed/app_packages`` or similar). |
| 293 |
|
| 294 |
You can then use the ``app-testbed`` folder to run the test suite for your app, |
| 295 |
For example, if ``module1.tests`` was the entry point to your test suite, you |
| 296 |
could run: |
| 297 |
|
| 298 |
.. code-block:: bash |
| 299 |
|
| 300 |
$ python app-testbed run -- module1.tests |
| 301 |
|
| 302 |
This is the equivalent of running ``python -m module1.tests`` on a desktop |
| 303 |
Python build. Any arguments after the ``--`` will be passed to the testbed as |
| 304 |
if they were arguments to ``python -m`` on a desktop machine. |
| 305 |
|
| 306 |
You can also open the testbed project in Xcode by running: |
| 307 |
|
| 308 |
.. code-block:: bash |
| 309 |
|
| 310 |
$ open app-testbed/iOSTestbed.xcodeproj |
| 311 |
|
| 312 |
This will allow you to use the full Xcode suite of tools for debugging. |
| 313 |
|
| 314 |
The arguments used to run the test suite are defined as part of the test plan. |
| 315 |
To modify the test plan, select the test plan node of the project tree (it |
| 316 |
should be the first child of the root node), and select the "Configurations" |
| 317 |
tab. Modify the "Arguments Passed On Launch" value to change the testing |
| 318 |
arguments. |
| 319 |
|
| 320 |
The test plan also disables parallel testing, and specifies the use of the |
| 321 |
``Testbed.lldbinit`` file for providing configuration of the debugger. The |
| 322 |
default debugger configuration disables automatic breakpoints on the |
| 323 |
``SIGINT``, ``SIGUSR1``, ``SIGUSR2``, and ``SIGXFSZ`` signals. |
| 324 |
|
| 325 |
App Store Compliance |
| 326 |
==================== |
| 327 |
|
| 328 |
The only mechanism for distributing apps to third-party iOS devices is to |
| 329 |
submit the app to the iOS App Store; apps submitted for distribution must pass |
| 330 |
Apple's app review process. This process includes a set of automated validation |
| 331 |
rules that inspect the submitted application bundle for problematic code. There |
| 332 |
are some steps that must be taken to ensure that your app will be able to pass |
| 333 |
these validation steps. |
| 334 |
|
| 335 |
Incompatible code in the standard library |
| 336 |
----------------------------------------- |
| 337 |
|
| 338 |
The Python standard library contains some code that is known to violate these |
| 339 |
automated rules. While these violations appear to be false positives, Apple's |
| 340 |
review rules cannot be challenged; so, it is necessary to modify the Python |
| 341 |
standard library for an app to pass App Store review. |
| 342 |
|
| 343 |
The Python source tree contains |
| 344 |
:source:`a patch file <Mac/Resources/app-store-compliance.patch>` that will remove |
| 345 |
all code that is known to cause issues with the App Store review process. This |
| 346 |
patch is applied automatically when building for iOS. |
| 347 |
|
| 348 |
Privacy manifests |
| 349 |
----------------- |
| 350 |
|
| 351 |
In April 2025, Apple introduced a requirement for `certain third-party |
| 352 |
libraries to provide a Privacy Manifest |
| 353 |
<https://developer.apple.com/support/third-party-SDK-requirements>`__. |
| 354 |
As a result, if you have a binary module that uses one of the affected |
| 355 |
libraries, you must provide an ``.xcprivacy`` file for that library. |
| 356 |
OpenSSL is one library affected by this requirement, but there are others. |
| 357 |
|
| 358 |
If you produce a binary module named ``mymodule.so``, and use you the Xcode |
| 359 |
build script described in step 7 above, you can place a ``mymodule.xcprivacy`` |
| 360 |
file next to ``mymodule.so``, and the privacy manifest will be installed into |
| 361 |
the required location when the binary module is converted into a framework. |