Create a Kivy iOS Project

This guide walks you through creating, configuring, and running your first Kivy project on iOS using PySwiftKit and psproject.

You will learn how to:

• Set up your Python environment
• Create a new Kivy iOS project
• Configure Xcode for your project
• Build and run your app on a real device
• Mirror your iPhone screen on macOS
• Install additional Python libraries into your Kivy iOS project

---

Install uv

Install the uv tool, which is a Python package manager and project initializer:

macOS and LinuxWindows

Open the terminal and use curl to download the script and execute it with sh:

curl -LsSf https://astral.sh/uv/install.sh | bash

Open powershell and use irm to download the script and execute it with iex:

curl -LsSf https://astral.sh/uv/install.ps1 | powershell

---

Initialize Your Kivy Project

Create and set up your project directory:

// Initialize a new Kivy iOS app called "hello-world"
$ psproject init hello-world

What this command do?

This command creates a new directory for your project called hello-world.

This will create the following structure:

hello-world
├── pyproject.toml
├── README.md
└── src
    └── hello_world
        ├── __init__.py
        ├── __main__.py
        └── app.py

The hello-world directory will contain all the necessary files for your Kivy app, including the main application code and configuration files. Later it will also contain the Xcode project folder.

Open the hello-world folder now in your preferred IDE. Here we'll open using VS Code:

code hello-world

Then, open the VS Code terminal and run the following command to install Kivy:

uv add kivy

Open src/hello_world/app.py and add a simple Kivy app:

from kivy.app import App
from kivy.lang import Builder

kv = """
Button:
    text: "Hello World"
"""


class MainApp(App):
    def build(self):
        return Builder.load_string(kv)


def main():
    app = MainApp()
    app.run()

Then run your app to ensure everything is set up correctly:

uv run hello-world

---

Edit pyproject.toml

Open pyproject.toml and edit the backends field under [tool.psproject] section:

[tool.psproject]
app_name = "hello-world"
backends = [
    "kivyschool.kivylauncher"
]
cythonized = false
extra_index = []
pip_install_app = false

The kivylauncher backend was added to the project, allowing you to build and run your Kivy app on iOS and macOS. It contains SDL2 framework and other necessary components for Kivy to function on iOS devices.

The app_name field is the name of your app as it will appear on the device. Avoid using spaces or special characters. This can be changed later when uploading the app to Apple Store.

Create a New Xcode Project

Generate a new Xcode project with psproject. Run this command from the working directory (hello-world):

// Run it from hello-world directory
$ psproject create xcode --open

Two things will happen:

1. New directory project_dist/xcode will be created with the following structure:

   hello-world
   ├── pyproject.toml
   ├── README.md
   ├── src
   │   └── hello_world
   │       ├── __init__.py
   │       ├── __main__.py
   │       └── app.py
   ├── uv.lock
   └── project_dist
       └── xcode
           ├── app
           ├── hello-world.xcodeproj
           ├── Resources
           ├── site_packages
           ├── Sources
           └── Support
   

2. The project will be opened in Xcode.

   

---

Update Site Packages

After creating the Xcode project, you need to install all Python dependencies into the iOS site-packages directories (iphoneos, iphonesimulator, macos). This command reads your pyproject.toml dependencies and installs them using host Python environment you set up earlier.

// Install Python packages for iOS
$ psproject update site-packages

---

Build and Run in Xcode

Open your new project in Xcode and select the simulator as the build target.

Press Ctrl+R to build and launch on the target device. The first time you run this, the build will fail with Xcode complaining about macro usage. Click in the error message and then click on Trust & Enable.

Then build and run again (Ctrl+R). You should see your Kivy app running in the simulator:

To run on a real iPhone/iPad:

• Connect your device and select it in Xcode's device list.
• Click on hello-world project in Xcode. Then on hello-world.xcodeproj, in Signing & Capabilities tab, Select your Apple Team. If you don't have an Apple Team, click on Team > Add Account... and sign in with your Apple ID. This will create a free developer account.
• Update the Bundle Identifier to something unique, like com.yourdomain.AppName. Otherwise you'll see an error about the bundle identifier being already in use (like in the image above).

• Build and launch (Ctrl+R)

  You will be prompted on your device about Untrusted Developer.

  On your iPhone: Settings > General > Device Management & VPN > [Your Developer Account] > Trust. Build and run again in Xcode.

---

Mirror iPhone Screen (Optional)

To mirror your iPhone screen on macOS:

• Open QuickTime Player
• Go to File > New Movie Recording
• Click the arrow next to the record button and select your iPhone as camera source

---

Continue to Swift Integration to learn how to bridge your Kivy app with native Swift code.