How to Run Your Kivy App On Your iPhone

Using Apple Silicon M1 chip

Hardware: Mac Mini with Apple M1 chip
MacOS: Monterey 12.0.1
Xcode: 13.1 with command line interface
Python: 3.9.2 (Intel installer)

If you have your own app you can use that and modify the steps or you can use my github repo (https://github.com/costa-rica/whatSticksKivy01.git) to follow steps exactly. I will keep it the same from now on.

This “How To” is mainly for building the environment because I was unable to find the exact guidance I needed for my app. My app is slightly more complicated than the tutorial apps which only use Kivy package. I met a seasoned Kivy user from a Kivy discord group that helped me get over the hump.

Order of steps

I am always concerned about the order of things because I usually have already done some steps before I stumble on a tutorial or instructions that get me where I want to go. Until we get to building the environment I don’t think the order of the Rosetta Terminal, Xcode install and Python matters. Partly because all that is done through Finder and install gui’s. So as long as you have the right versions of stuff in the next three sections you should be okay to just push forward.

I reformatted and did things many times because I was concerned about the apple silicon (intel) compatibility. The next section explains the Rosetta terminal and if you use that terminal it pretty much solves your compatibility issues.

Make a Rosetta Terminal

I apologize details here are a little vague. I recall this being straight forward. While trying to install Xcode I was prompted to Rosetta. So I hope that is what you experience. If not, here is Apple’s guidance on Rosetta 2 (https://support.apple.com/en-us/HT211861).

1. Install Rosetta 2 — you should be prompted to for this at some point
2. Duplicate terminal in Utilities
3. Rename duplicate terminal copy. I renamed it Terminal Rosetta
4. Right click on TerminalRosetta and in “Get info” click “Open using Rosetta”

Here is an article that goes into more detail on these steps: https://www.courier.com/blog/tips-and-tricks-to-setup-your-apple-m1-for-development

Install Xcode

Just go to App Store and search for Xcode. Get the latest version. This will also install a python3 on your computer. These instructions don’t use this version. And having this version on your computer won’t be an issue.

I was always worried about having too many versions and getting mixed up but don’t worry the next step I’ll show you how to install python so that when you call python3 you get the right version (not the Xcode version).

Once Xcode is installed you’ll be prompted to install the Command Line Tools for Xcode. Do that if you find yourself having problems you can go here to download: https://developer.apple.com/download/all/.

When you download it is a .dmg file and should be associated with whatever version of Xcode you have. Since I have Xcode 13.1 I have the Command Line Tools for Xcode 13.1

Fig 1. Screenshot of Apple Developer Site

Install python

I installed using this link: https://www.python.org/ftp/python/3.9.2/python-3.9.2-macosx10.9.pkg

If you navigate to python.org you can select which version you want to use. Here is a screen shot of all the options for 3.9.2 and the one you should use. I had many problems trying to use the universal installer. I’m not saying you can’t use the universal, but I use the Intel installer in these instructions.

Fig 2. Python Installer Package Download

Be sure to double click on the “install certificates command” and “update shell profile.command”. A window should pop up that looks like this:

Fig 3. Python Post Install Commands

Double click on the certificates and the update shell. The update shell command will add lines to your .zprofile that direct the “python3” command to this new version you are installing. This step is important so that you don’t use the python Xcode installs.

If the pop up doesn’t appear or you closed it by accident you can go here: /Applications/Python 3.9.

Build Environment

Ok here is where my Pulitzer Prize for journalism comes. It is also where I experienced a great deal of grief in this learning process. In particular, step #6 (“toolchain pip install <package>”) was something I had not seen or perhaps glossed over.

These steps should be followed in order. Notice that #5 might seem redundant if you already have kivy-ios in your requirements.txt, but make sure it is the last version of kivy-ios you install in your environment. You’ll see as I go through.

Keep it simple, do these steps from your Rosetta Terminal. All my instructions using a terminal are done through the Rosetta Terminal and from the project folder we create in this next step.

1. Build a “project folder”

This is a folder that will hold all your scripts, venv and kivy-ios stuff. Here is where I created my project folder:

/Users/nick/Documents/whatSticksBuild

This will be referred to as the “project folder” from here on. I have a tree diagram of the final product at the bottom.

2. Build venv (from Rosetta terminal inside your project folder).

python3 -m venv venv

3. Activate venv (from Rosetta terminal inside your project folder… I’m going to stop including this reminder but know I do everything with Kivy from this Rosetta Terminal).

source vent/bin/activate

4. Add your packages to this environment. If you’re using my github example you can first clone the repo in project folder then do pip install -r whatSticksKivy01/requirements.txt to avoid manually installing each package.

git clone https://github.com/costa-rica/whatSticksKivy01.git
pip install -r whatSticksKivy01/requirements.txt

5. Install kivy-ios. My requirements.txt has kivy-ios but this command will override the kivy-ios we just installed as well as add necessary directories (build, dist) to your project folder.

pip install git+https://github.com/kivy/kivy-ios.git

6. Toolchain builds, run these next in order. You may be able to combine the toolchain build and the toolchain pip but I haven’t got that comfortable yet. Toolchain build python3 kivy takes 20–30 minutes. Also, if something isn’t right you’ll usually get an error pretty quickly here.

toolchain build python3 kivy
toolchain build pillow
toolchain pip install kivymd
toolchain pip install pytz

7. Toolchain create. This is only one line in your terminal. This is exactly what I entered. The syntax goes “toolchain create”, then <app name> (and it can be anything although I’m not sure how to include spaces?) and <path> will most likely be different for you.

toolchain create wsh /Users/nick/Documents/whatSticksBuild/whatSticksKivy01

This creates a new directory in your project folder that has your compiled Xcode project. For me the new directory name is “wsh_app-ios”.

8. Open Xcode file

Fig 5. Folder Structure and Compiled Xcode Project

9. Select the project and make sure you’re signed in as a developer. If you have not created an account, you need to do this. It cost me $100 a year ago and it’s connected to my appleID. If you have an active developer account once you open you compiled Xcode project you first click on the project name on the top left. Then “Signing & Capabilities”. Then pick the team, which is probably just your name.

Fig 6. Xcode Signing & Capabilities

10. Make sure your phone is plugged in and selected by the play button. Then press the play button on the top left. At this point it will build to your iPhone.

Here is what my folder structure looks like in the end:

(venv) nick@Nicks-Mac-mini whatSticksBuild % tree -L 2
.
├── build
│   ├── freetype
│   ├── host_setuptools3
│   ├── hostlibffi
│   ├── hostopenssl
│   ├── hostpython3
│   ├── ios
│   ├── kivy
│   ├── libffi
│   ├── libjpeg
│   ├── openssl
│   ├── pillow
│   ├── pyobjus
│   ├── python3
│   ├── sdl2
│   ├── sdl2_image
│   ├── sdl2_mixer
│   └── sdl2_ttf
├── dist
│   ├── frameworks
│   ├── hostlibffi
│   ├── hostopenssl
│   ├── hostpython3
│   ├── include
│   ├── lib
│   ├── root
│   └── state.db
├── venv
│   ├── bin
│   ├── include
│   ├── lib
│   └── pyvenv.cfg
├── whatSticksKivy01
│   ├── DeviceAppDesign.pptx
│   ├── __pycache__
│   ├── kivyDesign.kv
│   ├── main.py
│   ├── requirements.txt
│   ├── tgelogo20210830_v2.png
│   └── utils.py
└── wsh_app-ios
├── LaunchImages
├── YourApp
├── bridge.h
├── bridge.m
├── icon-old.png
├── icon.png
├── main.m
├── wsh_app
├── wsh_app-Info.plist
└── wsh_app.xcodeproj

Other References

1. Here is a youtube tutorial that I found very helpful. If you did any Google/YouTube searching you’ve probably already found it.
2. There is a Kivy Discord server/chat room with many users. I found this helpful as well. You must be invited to the Kivy Discord server. I was invited by posting to the google Kivy support group here https://groups.google.com/g/kivy-users. Someone was kind enough to respond to my issue and invite me to the Discord server.

To be clear: there is very good documentation and a generous and active Kivy community — both of which helped me tremendously. Without the documentation provided by the Kivy team and help from the community I would not have gotten this far. So thank you to all them!

Regardless, this was not easy for me. I hope it will be easier for you. In case this helps I have tried to document all the steps that I need to do to build on my machine.

Best of luck!