Quick search

Create a package for IOS

New in version 1.2.0.


From the 4th march 2015, the toolchain for iOS has been rewritten. The previous instructions don’t work anymore (using build_all.sh). We strongly recommend you upgrade to the latest toochain which contains many improvements, including support for i386, x86_64, armv7, arm64 and the iOS emulators. If you must use the older version, try the old-toolchain tag in git.


Currently, packages for iOS can only be generated with Python 2.7. Python 3.3+ support is on the way.

The overall process for creating a package for IOS can be explained in 4 steps:

  1. Compile python + modules for IOS
  2. Create an Xcode project and link your source code
  3. Customize


You need to install some dependencies, like cython, autotools, etc. We encourage you to use Homebrew to install thoses dependencies:

brew install autoconf automake libtool pkg-config
brew link libtool
sudo easy_install pip
sudo pip install cython==0.21.2

For more detail, see IOS Prerequisites. Just ensure that everything is ok before starting the second step!

Compile the distribution

Open a terminal, and type:

$ git clone git://github.com/kivy/kivy-ios
$ cd kivy-ios
$ ./toolchain.py build kivy

Most of the python distribution is packed into python27.zip. If you experience any issues, please refer to our user group or the kivy-ios project page.

Create an Xcode project

Before proceeding to the next step, ensure your application entry point is a file named main.py.

We provide a script that creates an initial Xcode project to start with. In the command line below, replace test with your project name. It must be a name without any spaces or illegal characters:

$ # ./toolchain.py create <title> <app_directory>
$ ./toolchain.py create Touchtracer ~/code/kivy/examples/demo/touchtracer


You must use a fully qualified path to your application directory.

A directory named <title>-ios will be created, with an Xcode project in it. You can open the Xcode project:

$ open touchtracer-ios/touchtracer.xcodeproj

Then click on Play, and enjoy.


Everytime you press Play, your application directory will be synced to the <title>-ios/YourApp directory. Don’t make changes in the -ios directory directly.

Updating an Xcode project

Let’s say you want to add numpy to your project, but you didn’t have it compiled prior the XCode project creation. First, ensure to build it:

$ ./toolchain.py build numpy

Then, update your Xcode project:

$ ./toolchain.py update touchtracer-ios

All the libraries / frameworks necessary to run all the compiled recipes will be added to your Xcode project.


You can customize the build in many ways:

  1. Minimize the build/python/lib/python27.zip: 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...)
  2. Change the icon, orientation, etc... According to the Apple policy :)
  3. Go to the settings panel > build, search for “strip” options, and triple-check that they are all set to NO. Stripping does not work with Python dynamic modules and will remove needed symbols.
  4. Indicate a launch image in portrait/landscape for iPad with and without retina display.

Launch Images are supported. By default, XCode want you to build an Image Sets. This is your responsability to fill all the images needed for the Sets, depending of your target. However, Kivy use SDL, and as soon as the application starts the SDL main, the launch image will disapear. To prevent that, you need to have 2 files named Default.png and Default-Landscape.png, and put them in the Resources folder in Xcode (not in your application folder)

Known issues

Currently, the project has a few known issues (we’ll fix these in future versions):

  • You can’t export your project outside the kivy-ios directory because the libraries included in the project are relative to it.
  • Removing some libraries (like SDL_Mixer for audio) is currently not possible because the kivy project requires it.
  • And more, just too technical to be written here.


Application quit abnormally!

By default, all the print statements to the console and files are ignored. If you have an issue when running your application, you can activate the log by commenting out this line in main.m:


Then you should see all the Kivy logging on the Xcode console.

How can Apple accept a python app ?

We managed to merge the app binary with all the libraries into a single binary, called libpython. This means all binary modules are loaded beforehand, so nothing is dynamically loaded.

Have you already submited a Kivy application to the App store ?

Yes, check:

For a more complete list, visit the Kivy wiki.