Need help with kivy-ios?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

565 Stars 190 Forks MIT License 818 Commits 40 Opened issues


Toolchain for compiling Python / Kivy / other libraries for iOS

Services available


Need anything else?

Contributors list

Kivy for iOS

kivy-ios PyPI version Backers on Open Collective Sponsors on Open Collective

This toolchain is designed to compile the necessary libraries for iOS to run your application and manage the creation of the Xcode project.

We do not provide any binary distributions of this toolchain. You do need to compile it at least once before creating your Xcode project.

The toolchain supports:

  • iPhone Simulator (x86_64)
  • iPhone / iOS (arm64)

These recipes are not ported to the new toolchain yet:

  • lxml

Installation & requirements

Before we start, we strongly advise to use a Python virtual environment to install Python packages.

  python3 -m venv venv
  . venv/bin/activate

Install Kivy for iOS from PyPI with pip like any Python package.

  pip3 install kivy-ios

Additionally you would need few system dependencies and configuration.

  • Xcode 10 or above, with an iOS SDK and command line tools installed:

    xcode-select --install

  • Using brew, you can install the following dependencies:

    brew install autoconf automake libtool pkg-config brew link libtool

Using the toolchain

Any Python extensions or C/C++ library must be compiled: you need to have what we call a

to compile it. For example, Python, libffi, SDL2, SDL_image, freetype... all the dependencies, compilation and packaging instructions are contained in a

You can list the available recipes and their versions with:

$ toolchain recipes
audiostream  master
click        7.1.2
cymunk       master
ffmpeg       n4.3.1
ffpyplayer   v3.2
flask        1.1.2
freetype     2.5.5
hostlibffi   3.2.1
hostopenssl  1.1.1g
hostpython3  3.7.1
ios          master
itsdangerous 1.1.0
jinja2       2.11.2
kivy         1.10.1
libffi       3.2.1
libjpeg      v9a
libpng       1.6.26
markupsafe   1.1.1
moodstocks   4.1.5
numpy        1.16.4
openssl      1.1.1g
photolibrary master
pillow       6.1.0
plyer        master
pycrypto     2.6.1
pykka        1.2.1
pyobjus      master
python3      3.7.1
pyyaml       3.11
sdl2         2.0.8
sdl2_image   2.0.0
sdl2_mixer   2.0.0
sdl2_ttf     2.0.12
werkzeug     1.0.1

Then, start the compilation with:

$ toolchain build python3 kivy

You can build recipes at the same time by adding them as parameters:

$ toolchain build python3 openssl kivy

Recipe builds can be removed via the clean command e.g.:

$ toolchain clean openssl

You can install package that don't require compilation with pip::

$ toolchain pip install plyer

The Kivy recipe depends on several others, like the sdl* and python recipes. These may in turn depend on others e.g. sdl2_ttf depends on freetype, etc. You can think of it as follows: the kivy recipe will compile everything necessary for a minimal working version of Kivy.

Don't grab a coffee, just do diner. Compiling all the libraries for the first time, 2x over (remember, 2 archs, x86_64, arm64) will take time.

For a complete list of available commands, type:

$ toolchain

Create the Xcode project

can create the initial Xcode project for you::
$ toolchain create  <app_directory>
$ toolchain create Touchtracer ~/code/kivy/examples/demo/touchtracer

Your app directory must contain a A directory named

will be created, with an Xcode project in it. You can open the Xcode project using::
$ open touchtracer-ios/touchtracer.xcodeproj

Then click on

, and enjoy.

Did you know ?

Everytime you press

, your application directory will be synced to the
directory. Don't make changes in the -ios directory directly.

Configuring your App

You can configure and customize your app in various ways:

  • Set the icon and launch images in XCode. Note that XCode requires that you specify these assests per device or/and iOS version.

  • When you first build your XCode project, a 'main.m' file is created in your XCode project folder. This file configures your environment variables and controls your application startup. You can edit this file to customize your launch environment.

  • Kivy uses SDL, and as soon as the application starts the SDL main, the launch image will disappear. To prevent that, you need to have 2 files named

    , and put them in the
    folder in Xcode (not in your application folder)

Did you know ?

If you wish to restrict your apps orientation, you should do this via the 'export_orientation' function in 'main.m'. The XCode orientation settings should be set to support all.

Using recipes

Recipes are used to install and compile any libraries you may need to use. These recipes follow the same format as those used by the Python-for-Android sister project. Please refer to the recipe documentation there for more detail.

Reducing the application size

If you would like to reduce the size of your distributed app, there are a few things you can do to achieve this:

  • Minimize the

    : this contains all the python modules. You can edit the zip file and remove all the files you'll not use (reduce encodings, remove xml, email...)
  • Go to the settings

    , search for
    options, and triple-check that they are all set to
    . Stripping does not work with Python dynamic modules and will remove needed symbols.
  • By default, the iOS package compiles binaries for all processor architectures, namely x8664 and arm64 as per the guidelines from Apple. You can reduce the size of your ipa significantly by removing the x8664 architecture as they are used only for the emulator.

The procedure is to first compile/build all the host recipes as is:

  toolchain build hostpython3

Then build all the rest of the recipes using --arch=arm64 arguments as follows:

  toolchain build python3 kivy --arch=arm64

Note that these packages will not run in the iOS emulators, so use them only for deployment.


toolchain  []

Available commands: build Build a recipe (compile a library for the required target architecture) clean Clean the build of the specified recipe distclean Clean the build and the result recipes List all the available recipes status List all the recipes and their build status

Xcode: create Create a new xcode project update Update an existing xcode project (frameworks, libraries..) launchimage Create Launch images for your xcode project icon Create Icons for your xcode project pip Install a pip dependency into the distribution pip3 Install a pip dependency into the python 3 distribution


Alternatively, it's also possible to clone the repository and use all the described commands in the above sections. Clone and install it to your local virtual environment:

git clone
cd kivy-ios/
python3 -m venv venv
. venv/bin/activate
pip install -e .

Then use the
python --help


Fatal error: "stdio.h" file not found

You need to install the Command line tools:

xcode-select --install

Error: SDK "iphonesimulator" cannot be located

Xcode path is not set up correctly. Run the following command to fix this:

sudo xcode-select --switch 
 to the path that reflects your XCode installation, usually is 

Bitcode is partially supported now (Xcode setting ENABLE_BITCODE can be set to Yes).

  • Supported recipes: python3, kivy, sdl2, sdl2image, sdl2mixer and libffi

You don't have permissions to run

It is due to invalid archs, search for them and check it. Maybe you targetted a simulator but have only arm64. Maybe you want to target your iPad but it as only x86_64.

Why does the python multiprocess/subprocess module not work?

The iOS application model does not currently support multi-processing in a cross-platform compatible way. The application design focuses on minimizing processor usage (to minimize power consumption) and promotes an alternative concurrency model.

If you need to make use of multiple processes, you should consider using PyObjus to leverage native iOS functionals for this.


If you need assistance, you can ask for help on our mailing list:

We also have a Discord channel:

  • Server :
  • Channel : #support


We love pull requests and discussing novel ideas. Check out our contribution guide and feel free to improve Kivy for iOS.

The following mailing list and IRC channel are used exclusively for discussions about developing the Kivy framework and its sister projects:

Discord channel:

  • Server :
  • Channel : #dev


Kivy for iOS is released under the terms of the MIT License. Please refer to the LICENSE file.


Thank you to all our backers! 🙏 [Become a backer]


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.