Put Kivy Application on iPhone

updated Oct 2023

9 min readOct 14, 2023

Putting Kivy applications on your iPhone can be challenging because you are working with multiple technologies. I’ve gone through this process a few times and each time I encounter new challenges.

In this article I’m going to go through the latest process. The goal is to have a current set of instructions and most importantly provide some insight in my troubleshooting approaches.

While this article is intended to be a general step by step procedure for installing a Kivy application to your iPhone, it references the Open Mindset project. If you want to practice building it you can clone the repository.

My Hardware and System

Mac M1 (arm64)
Ventura 13.5.2
Xcode 15
iOS 17.0
Python 3.10

Folder structure

Here is an oversimplified layout of my folder structure. This was a bit confusing to me at the beginning. The key is that when working with toolchain commands make sure you are in the folder that you installed your toolchain environment (kivy-ios).

Step 1: Create Python Environment

Navigate into the location you plan to keep your venv (Python virtual environment). The first line below creates the virtual environment and the second line activates it.

python -m venv mindset03
.mindset03/bin/activate

Install the packages

In Open Mindset we use pip tools so if you want to follow along you can do the following commands otherwise you can just pip install or however you want to install your packages.

python -m pip install pip-tools
pip-compile requirements.in
pip-sync

At this point you should be able to navigate into the repository directory /poc-mobile-python, run:

python main.py

Here is what Open Mindset looks like when your run it from your Python environment.

If not maybe you’ve encountered a ModuleNotFoundError: No module named ‘kivy.core.window._window_sdl2’ problem. I detailed why this might be and how I resolved it in the Problems Encountered section towards the bottom of this article.

Step 2: Kivy-ios

I put kivy-ios as a separate step, even though it is just part of your venv, because it is the key package to transform your Python project into an Xcode project that will eventually get your app on your iPhone.

pip install kivy-ios

The kivy-ios package provides toolchain. Toolchain is both the (1) command and (2) pacakge/suite/collection of software available in kivy-ios package. toolchain suite of software will convert the python project (poc-mobile-python) to an Xcode project.

Step 3: Create toolchain environment

Once kivy-ios is installed in venv (I’ve called mine mindset03 in for this article), navigate to the folder you plan to save your Xcode project.

You will be able to build many Xcode projects in here, but you must set up the toolchain environment first. To do this, you will at least need kivy and python3. However, our project needed other packages as well. You’ll probably find this is the issue for you as well. In your terminal type:

toolchain build python3 kivy pillow libffi ffpyplayer

This step will take a while, 10–20 mins if you have a good connection. You’ll see your terminal very active as it’s downloading/installing/or whatever else it needs to do.

This will create two folders in your KivyBuilds: “builds” and “dist”.

Then for Open Mindset you will also need.

toolchain pip install kivymd kaki watchdog event_bus

Step 4: Create Xcode project

From your terminal still inside your KivyBuilds folder enter “toolchain create” + [any name you want to give your app] + [path to Python Kivy project]

toolchain create openmindset ~/Documents/poc-mobile-python

KivyBuilds folder where toolchain environment is kept

Then you can double click to open your Xcode project folder

If everything goes well, you can run the application on the simulator by clicking in the area where the right arrow is pointing to and select a device. Then click the play button (left blue arrow).

If there are any errors they will show up in the bottom. One common error is that a module is missing. To trouble shoot this see ModuleNotFoundError: No module named ‘kivymd’ section at the bottom.

Step 5: Sign in to Xcode

To build to your iPhone you will need to sign in your Apple Developer account.

Xcode sign in via Apple Developer account credentials

If you do not have an Apple Developer account i.e. a team under the dropdown I believe you get one here https://developer.apple.com/programs/.

Step 6: Build to your iPhone

After signing into your Apple Developer account, you can build to your iPhone by changing the destination of your build. Here I am building to my iPhone called “Leafy-outrider”, but you may have a different name.

If you see these errors, I have fix in the :

· Building for ‘iOS’, but linking in dylib (/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator.sdk/System/Library/Frameworks/OpenGLES.framework/OpenGLES.tbd) built for ‘iOS-simulator’
· Linker command failed with exit code 1 (use -v to see invocation)

If you’ve gotten this far you should be proud of yourself. This is not easy. The learning process for this is not linear because you’re dealing with multiple technologies and many variables.

If your app is on your phone great let’s move on. If not, don’t worry just spend some more time on the problem and hopefully one of my trouble shooting areas can help you.

Next, let me explain App Store Connect and TestFlight, because these are two steps on the way to disseminating your app on the app store.

What is App Store Connect?

In short, App Store Connect is a one-stop shop for you to manage you apps on the App Store and just prior to disseminating it on the App Store.

What is TestFlight?

TestFlight is a service that allows you to test your application in an environment similar to the App Store (i.e. download from App Store Connect on to your iPhone). It is part of App Store Connect.

What to do to setup your Xcode project for TestFlight

Minimum Deployments

By default your toolchain build Xcode project will probably be set to 9.0. This is going to give you problems. The further back you go the more stuff you will need to make it compatible or accepted by App Store Connects

Encryption Compliance

To avoid dealing this with this question in your Xcode project you should be able to add “ITSEncryptionHasNonStandardTypes” and value “NO” to your info.plist

Encryption information from apple with screenshot of adding the “App Encryption Export Compliance Code” Key to your info.plist.

Adding Encryption Details for App Store Connect

If you get this using the Open Mindset version we select “Standard encryption”. Here is more information on this topic: https://developer.apple.com/documentation/security/complying_with_encryption_export_regulations.

Post Your Application on App Store Connect / TestFlight

This is an exciting step because this means you will be able to share your application with others.

To TestFlight Step 1: Archive

From inside Xcode select Product menu > Archive. This creates a file that will be submitted to App Store Connects

This step will take you directly to another window once the file is built. See next step.

To TestFlight Step 2: Distribute App

To distribute the App if you came directly from Product menu > Archive. Then you will see the prompt below. But if you closed out of it or want to get back to this for whatever reason you’ll want to go to Organizer, which is found in Xcode > Window menu > Organizer.

Problems Encountered

Here are some of the errors I encountered and how I resolved them:

ModuleNotFoundError: No module named ‘kivy.core.window._window_sdl2’

This problem I found was solved by installing the following packages into my Homebrew environment:

brew install sdl2_image
brew install sdl2_mixer
brew install sdl2_ttf

If they are installed do:

brew upgrade

These packages are required at the time of writing this article if you are building the app using the kivy github master, which will show up as kivy==2.3.0.dev0 in your pip list. If you simply did pip install kivy you would get kivy==2.2.1. Both versions work on my computer. However, if you’re using the github master you may have encounter this missing module error.

SDK iphonesimulator cannot be located

If you have encountered this error it will look like this:

File “~/Documents/_environments/mindset/lib/python3.10/site-packages/sh.py”, line 826, in handle_command_exit_code
raise exc
sh.ErrorReturnCode_1:
RAN: /usr/bin/xcrun — sdk iphonesimulator — show-sdk-path
STDOUT:
STDERR:
xcrun: error: SDK “iphonesimulator” cannot be located
xcrun: error: SDK “iphonesimulator” cannot be located
xcrun: error: unable to lookup item ‘Path’ in SDK ‘iphonesimulator’

Potential Solution: Then there is an issue with mapping your Xcode. Most likely it is not installed or installed in a different path or different name than expected.

To install you can just to:

xcode-select — install

If you are using a Mac then Xcode should be named “Xcode” and it should be in your Applications/.

To verify this you can just do:

xcode-select -p

And this should return

If you see the name is just different like /Library/Developer/CommandLineTools like below

Then you probably named it something else after downloading. You can just manually rename your Xcode to “Xcode”.

If it’s ins a different place ChatGPT suggests:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

…but honestly, I have not successfully done this. I have uninstall/reinstalled Xcode and now I have everything in the right place. So hopefully, worst case for you is you uninstall/reinstall Xcode.

ModuleNotFoundError: No module named ‘kivymd’

This could be for any number of packages that may be in your venv but not in the toolchain environment.

Potential Solution: Honestly, it’s not entirely clear to me which ones must absolutely be added because there are some packages in my venv that I never add to toolchain but the application still works. Regardless, if you encounter this error try adding the missing package to your toolchain environment with this command (inside your KivyBuilds folder or wherever you installed the `toolchain build kivy`):

toolchain pip install kivymd

Problems linking dylib

I am having problems building the application to my iPhone. Here is the error that I believe is causing my issue:

Building for ‘iOS’, but linking in dylib (/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator.sdk/System/Library/Frameworks/OpenGLES.framework/OpenGLES.tbd) built for ‘iOS-simulator’

Here is a screenshot of the warnings when I try to build it:

Potential Solution: Change Xcode name.

It’s not elegant and certainly not right, but it works and I’m moving on. If someone has any suggestions or a better solution to the errors, please share. Even if it’s just an idea for where to look — often someone else’s suggestions lead to solutions.

So even though this causes other problems with the toolchain environment, I’m changing the name here. I usually change it to “Xcode15” to build to my iPhone because this is version 15 that I am using. Then I change it back to “Xcode” when I have to use “toolchain” commands.

Invalid bundle structure… binary file is not permitted

When trying to Distribute your app to App Store Connect you might find an error like this

Potential Solution: I have solved this particular issue by removing this binary from the ~/KivyBuilds/dist/root/python3/lib/python3.10/site-packages/ directory

I have seen other similar problems that say remove files form the Targets > Build Phases > Link Binary With Libraries.

In Conclusion

Building between Python Kivy to Xcode / iOS is a bit of a challenge but it works. If you’re having problems just keep at it. A solution will appear — even if it’s a hacky one that temporarily serves the purpose.