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:

// Create project directory and enter it
$ mkdir hello-world-project
$ cd hello-world-project

// Initialize a new Kivy iOS app called "hello-world"
$ psproject init hello-world
$ touch hello-world/src/hello_world/main.py

What these commands do?

These commands create a new directory for your project called hello-world-project, initialize a new Kivy project named hello-world, and create a new Python file at hello-world/src/hello_world/main.py.

This will create the following structure:

hello-world-project
└── hello-world
    ├── .gitignore
    ├── .python-version
    ├── pyproject.toml
    ├── README.md
    └── src
        └── hello_world
            ├── __init__.py
            └── main.py

The hello-world-project directory contains only the hello-world now, but later it will also contain the Xcode project folder. It's important to keep the structure organized in this way.

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/main.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)


app = MainApp()
app.run()

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

uv run src/hello_world/main.py

---

Edit pyproject.toml

Open pyproject.toml and edit the following fields under [pyswift.project] section:

[pyswift.project]
backends = [
    "kivylauncher"
]
bundle_id = "org.pyswift.hello-world"
folder_name = "hello-world-xcode"
name = "HelloWorld"
pip_install_app = false
platforms = [ "iphoneos" ]
swift_sources = []

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

The folder_name specifies the name Xcode will use for the project folder. Normally you would like to just add -xcode suffix to your project name.

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

Create a New Kivy iOS Project

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

// Run it from hello-world-project directory
$ psproject create --uv hello-world -f

Two things will happen:

1. New directory hello-world-xcode will be created with the following structure:

   hello-world-project
   ├── hello-world
   │   ├── pyproject.toml
   │   ├── README.md
   │   ├── src
   │   │   └── hello_world
   │   │       ├── __init__.py
   │   │       ├── main.py
   │   └── uv.lock
   └── hello-world-xcode
       ├── app
       ├── HelloWorld.xcodeproj
       ├── IphoneOS
       ├── requirements.txt
       ├── site_packages.iphoneos
       ├── site_packages.iphonesimulator
       └── Support
   

2. The project will be opened in Xcode.

   

---

Build and Run in Xcode

Open your new project in Xcode, press Ctrl+R to build and launch on the Simulator.

To run on a real iPhone/iPad:

• Connect your device and select it in Xcode's device list.
• Click on HelloWorld project in Xcode. Then on HelloWorld.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.