Skip to content

ksproject

Compile Python + Kivy apps for Android and iOS — toolchain setup, native builds, and dependency management in a single CLI.

New Project Configuration GitHub

Android + iOS Native Builds

UV Powered Python Toolchain

Extensible Plugin Ecosystem

Why ksproject?

One tool to go from Python code to native mobile apps — no manual Gradle or Xcode setup.

  • Instant Project Setup

    uv run ksproject init creates a complete project with Kivy app template, pyproject.toml config, and all the scaffolding for mobile builds — ready in seconds.

    Create a project

  • Android Builds

    Automatic SDK/NDK/Java installation, Gradle project generation, multi-arch APK/AAB builds, keystore signing, and one-command deploy to emulators or physical devices.

    Build for Android

  • iOS & macOS Builds

    XcodeGen-based project generation with Python.xcframework, SDL2, App Store archiving, and one-command deploy to simulators or devices via xcodebuild.

    Build for iOS

  • Plugin Ecosystem

    Install pip packages that automatically inject Java sources, Gradle dependencies, Android permissions, and iOS frameworks into your app at build time.

    Explore plugins

  • Automatic Toolchain

    ksproject downloads and manages Android SDK, NDK, Java (via sdkman), build tools, and system images — no manual setup required.

    Configuration

  • pyproject.toml Driven

    All configuration lives in a single pyproject.toml under [tool.kivy-school] — package name, permissions, services, build variants, and more.

    Full reference

Quick Start

From zero to running on your phone in three commands.

# 1. Create a new project
uv init --package myapp --python 3.13
cd myapp
uv add git+https://github.com/kivy-school/ksproject --dev
uv run ksproject init

# 2. Build for Android (SDK/NDK auto-installed on first run)
uv run ksproject android build

# 3. Run on a connected device
uv run ksproject android run --name "Pixel_8"

How It Works

  • Initialize

    uv run ksproject init scaffolds a UV-managed Python project with Kivy app sources, a pyproject.toml containing [tool.kivy-school] config, and platform templates.

  • Configure

    Define your app name, package ID, permissions, services, and dependencies in pyproject.toml. ksproject reads everything from there — no external config files.

  • Build

    uv run ksproject android build or uv run ksproject apple ios build generates native project files, installs cross-compiled site-packages per architecture, and compiles the final app.

  • Run

    Deploy directly to emulators, simulators, or physical devices. ksproject handles ADB, simctl, and devicectl for you.

Explore the Documentation

  • New Project

    Create a complete Kivy project with all the scaffolding for Android and iOS builds in one command.

    Get started

  • pyproject.toml Reference

    Complete reference for every configuration key — Android package names, iOS bundle IDs, permissions, services, and build settings.

    Configuration

  • Android Guide

    Build APKs, AABs, and AARs. Deploy to emulators and devices. Understand how site-packages, Java, and Gradle configs are merged.

    Android docs

  • iOS Guide

    Build for simulators and devices. Understand how xcframeworks and site-packages work in the Xcode project.

    iOS docs

  • Plugin Development

    Create pip packages that inject Java sources, Gradle dependencies, and permissions into apps that install them.

    Plugin guide

  • Wheelhouse

    Drop your own platform wheels — a patched Kivy, an unreleased dependency — into wheelhouse/ and ksproject uses them in mobile builds.

    Wheelhouse guide