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:

mkdir myproject
cd myproject
uv init
uv python pin 3.11.6
uv add kivy
mkdir src
mv main.py src/

This will create the following structure:

myproject/
├── src
│   └── main.py
├── .gitignore
├── .python-version
├── .pyproject.toml
└── README.md

Open src/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/main.py

---

Create a New Kivy iOS Project

Generate a new Kivy iOS project with psproject:

psproject kivy create HelloWorld -p ./src

Two things will happen:

1. New directory HelloWorld will be created with the following structure:

   HelloWorld/
   ├── HelloWorld.xcodeproj
   ├── py_src
   │   └── main.py
   ├── Resources
   │   ├── Images.xcassets
   │   ├── site-packages
   │   ├── YourApp
   │   ├── icon.png
   │   └── Launch Screen.storyboard
   ├── Sources
   │   ├── Main.swift
   │   └── YourApp.swift
   └── Info.plist
   

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.