kivyforge

kivyforge is a declarative, PEP 621-aligned build toolchain for Kivy (and other Python) apps. You describe your app once in pyproject.toml; kivyforge resolves your dependencies into a lockfile and packages the app for the platform you target. It is the successor to kivy-ios, python-for-android, and buildozer, unifying their per-platform workflows behind a single declarative configuration.

The goal is one toolchain for every platform Kivy runs on — Android, iOS, Linux (including Raspberry Pi), macOS, and Windows.

📖 Documentation: https://elliotgarbus.github.io/kivyforge/ — installation, quickstarts for every platform, the configuration and CLI reference, and troubleshooting. Build it locally with pip install -e ".[docs]" then mkdocs serve.

Status: early development — iOS + macOS + Linux (x86_64 and Raspberry Pi) + Windows + Android. kivyforge targets iOS (resolve into pylock.ios.toml, download the official Python.xcframework + prebuilt iOS wheels, generate an Xcode project), macOS (resolve into pylock.macos.toml, bundle a relocatable python-build-standalone CPython + wheels into a signed, double-clickable .app), Linux (resolve into pylock.linux.toml, bundle a PBS gnu/glibc CPython + manylinux wheels into an AppImage — with a run-from-folder AppDir substrate; x86_64 PCs and aarch64 Raspberry Pi boards, the latter cross-built from an x86_64 host), Windows (resolve into pylock.windows.toml, bundle a PBS MSVC CPython + win_amd64 wheels into a run-from-folder onedir with a windowed launcher .exe, optionally Authenticode-signed), and Android (resolve into pylock.android.toml, assemble the official python.org Android runtime + per-ABI android_* wheels into a generated Gradle project, and produce a signed .apk/.aab — with pyjnius as a prebuilt wheel, no per-app compilation). If you need a shipping toolchain today, use kivy-ios 2.x, python-for-android, or buildozer.

Currently supported targets

Target	Architectures	Output	Signing	Build host
iOS device	arm64 (iPhone / iPad)	generated Xcode project → .app	Apple Developer signing via Xcode	macOS + Xcode
iOS Simulator	arm64	generated Xcode project → .app	none required	macOS + Xcode
Android device / emulator	arm64_v8a, x86_64	generated Gradle/AGP project → .apk / .aab	auto debug keystore, or release keystore (v1–v4 schemes)	Windows, macOS, or Linux + JDK/Android SDK/NDK
macOS	arm64 (Apple Silicon)	.app	ad-hoc (default) or Developer ID sign + notarize + staple	macOS (Apple Silicon)
Linux	x86_64 (glibc ≥ 2.17), aarch64	.AppImage / AppDir	none	Linux
Raspberry Pi (Pi 4 / Pi 5, 64-bit Raspberry Pi OS)	aarch64	.AppImage (a Linux target — see Build for Raspberry Pi)	none	x86_64 Linux (cross-build; WSL2 works)
Windows	amd64	onedir folder + windowed launcher .exe	optional Authenticode (unsigned by default)	Windows

Desktop targets (macOS / Linux / Windows) bundle a self-contained runtime + wheels; on Linux (including Raspberry Pi), libGL/EGL and X11/Wayland come from the host. Raspberry Pi is built as archs = ["aarch64"] on the Linux backend; you do not install kivyforge on the Pi. It is tested on a Raspberry Pi 5; the Pi 4 is supported but untested, and 32-bit Raspberry Pi OS is not supported. Building for iOS requires a Mac with Xcode; Android builds on any of the three desktop hosts.

Apple targets are Apple Silicon only. kivyforge does not build Intel (x86_64) macOS apps or pin the Intel iOS-Simulator slice: macOS 27 stops installing on Intel hardware and macOS 28 removes Rosetta, so an Intel slice would be one nothing can execute or validate. universal2 wheels are still resolved normally — they contain arm64.

kivyforge builds on the work of the Kivy Team.

Requirements

Each target platform has its own host requirements. Building for iOS requires macOS (Xcode-based), so the iOS workflow below is useful only on a Mac:

• macOS with the full Xcode 15 or newer installed from the Mac App Store. (xcode-select --install installs only the command-line tools, which are not enough for iOS.) Point the tools at it:

  sudo xcode-select --switch /Applications/Xcode.app
  

• Accept the Xcode license once:

  sudo xcodebuild -license
  

Building for Android works from Windows, macOS, or Linux, and needs three user-installed prerequisites (kivyforge never installs a host toolchain — it only detects one):

• A JDK 17 to 23 on PATH or JAVA_HOME (the range the pinned Gradle can run on; Android Studio's bundled JDK may be newer than that).
• The Android SDK (ANDROID_HOME/ANDROID_SDK_ROOT), with the compile_sdk platform, build-tools, platform-tools, and recorded SDK licenses (see the Android quickstart). Android Studio's SDK Manager covers all of it.
• The NDK — required for every Android build, not just apps with native code: it compiles the bootstrap's native launcher (libmain.so).

kivyforge doctor -p android checks each of these and prints the sdkmanager command for whatever is missing. Add an AVD (or attach a device with USB debugging enabled) before kivyforge run.

Installation

kivyforge is a command-line tool and needs Python 3.13 or newer. It is on PyPI, but every release so far is a pre-release (currently 3.0.0.dev1). pipx and pip skip pre-releases unless you opt in, so their commands below carry a pre-release flag; uv picks a pre-release when no stable release exists, so it needs none. The recommended installer is uv, which installs it into its own isolated environment and puts kivyforge on your PATH:

  uv tool install kivyforge

If your shell reports that kivyforge is not found, run uv tool update-shell and open a new terminal. Upgrade or remove it later with uv tool upgrade kivyforge / uv tool uninstall kivyforge. Once a stable release is published, the pre-release flags are no longer needed.

Alternatives: pipx (pipx install --pip-args="--pre" kivyforge), or pip inside a virtual environment so it does not collide with other projects:

  python3 -m venv .venv
  . .venv/bin/activate          # Windows PowerShell: .venv\Scripts\Activate.ps1
  pip install --pre kivyforge

Check the install with kivyforge --version and kivyforge capabilities. The install also provides a short alias, kf. For the full walk-through, see Install kivyforge. To work on kivyforge itself, see Development.

Mobile examples need no local wheel-building. Kivy (2.3.1 and 3.0), pyobjus, and pyjnius resolve from the kivy-mobile-wheels index — a companion repo of first-party iOS/Android cross-builds published as a static PEP 503 index — so kivyforge lock just works against any mobile example. scripts/build_ios_wheels.sh / scripts/build_pyobjus_ios_wheels.sh remain for cross-building your own iOS wheels locally (e.g. to vendor one via a path lock instead of the index); neither is required to run the examples.

Desktop needs no wheel-building either. The desktop examples under examples/desktop/ build straight from PyPI — Kivy 2.3.1 ships universal2 macOS wheels, so there is no macOS wheel-building step. Kivy 3.0 has no public desktop wheels yet, which is why desktop examples stay on 2.3.1; the iOS mobile examples need 3.0 for its structural mobile changes, while the Android examples run either generation (2.3.1/SDL2 for most, 3.0/SDL3 for hello-sdl3) depending on which bootstrap they gate.

Detailed documentation. For the full design and reference docs — the cross-platform model, the pyproject.toml / pylock.<platform>.toml schemas, artifact distribution, the CLI shape, and the per-platform backends (Android, iOS, macOS, Linux, Windows) — start with the kivyforge design overview.

Quick start (iOS)

The workflow below targets iOS; see Quick start (Android), (macOS), (Linux), and (Windows) further down for the other backends. Run every command from the directory that contains your app's pyproject.toml.

  # 1. Seed [tool.kivy] / [tool.kivy.ios] config into pyproject.toml
  kivyforge init

  # 2. Resolve dependencies into pylock.ios.toml
  kivyforge lock

  # 3. Download artifacts and generate <app>-ios/<app>.xcodeproj
  kivyforge build

  # 4a. Open the project in Xcode and press Run...
  kivyforge open

  # 4b. ...or build, install, and launch on the simulator from the CLI
  kivyforge build --simulator
  kivyforge run --simulator

Quick start (macOS)

macOS needs only the Xcode command-line tools (codesign), not the full Xcode IDE. The macOS backend bundles a relocatable CPython + your wheels into a signed .app:

  # 1. Seed [tool.kivy] / [tool.kivy.macos] config (or add the overlay by hand)
  kivyforge init            # then add a [tool.kivy.macos] table

  # 2. Resolve dependencies + pin the runtime into pylock.macos.toml
  kivyforge lock -p macos

  # 3. Build the .app (arm64)
  kivyforge build -p macos

  # 4a. Launch it (foreground, so you see stdout/tracebacks)
  kivyforge run -p macos

  # 4b. ...or produce the finished, signed distributable
  kivyforge package -p macos      # -> build/macos/<App>.app

package is config-driven: with no signing config it ships the ad-hoc-signed .app (runs locally; downloaded copies hit Gatekeeper). For distribution to other Macs, configure [tool.kivy.macos.signing] with a Developer ID Application identity (paid Apple Developer Program) and a notary_profile (created with xcrun notarytool store-credentials) — then the same command deep-signs with Hardened Runtime, notarizes, and staples the .app so Gatekeeper trusts it everywhere. --no-notarize skips the submission. (Hit errSecInternalComponent from codesign? See the FAQ entry on corrupted keychain ACLs.)

kivyforge doctor -p macos reports environment + project health (host, codesign, arch coverage, runtime floor, signing identity, notary setup, reachable hosts).

Quick start (Linux)

The Linux backend bundles a relocatable CPython + your manylinux wheels into an AppImage (the default) or a run-from-folder AppDir. It needs a Linux host (the runtime is a gnu/glibc build); no compiler or FUSE is required at build time.

  # 1. Add a [tool.kivy.linux] table to pyproject.toml (app_id, icons, ...)

  # 2. Resolve dependencies + pin the runtime into pylock.linux.toml
  kivyforge lock -p linux

  # 3. Build the AppDir (build/linux/<App>.AppDir)
  kivyforge build -p linux

  # 4a. Launch it (runs ./AppRun directly — the fast dev loop, no FUSE)
  kivyforge run -p linux

  # 4b. ...or produce the distributable
  kivyforge package -p linux              # -> dist/linux/<app>-<ver>-x86_64.AppImage
  kivyforge package -p linux -f folder    # -> the AppDir itself

The AppImage embeds a static-FUSE runtime, so recipients need no libfuse2; ./<App>.AppImage --appimage-extract-and-run is the universal no-FUSE fallback. The host contract is explicit: the bundle never vendors libGL/libEGL or a display server, so the host must provide glibc ≥ the artifact's effective floor, libGL.so.1/libEGL.so.1, and an X11 or Wayland session.

kivyforge doctor -p linux reports environment + project health (Linux/glibc host, GL libraries, display session, glibc floor, arch coverage, generated .desktop validity, reachable hosts).

Raspberry Pi

Raspberry Pi is a first-class Linux target, not a separate platform. Set archs = ["aarch64"] in [tool.kivy.linux], then cross-build the AppImage on an x86_64 Linux machine (WSL2 works) and copy it to a Pi 4 or Pi 5 running 64-bit Raspberry Pi OS with a desktop:

  kivyforge lock -p linux
  kivyforge package -p linux -f appimage --arch aarch64   # -> dist/linux/<app>-<ver>-aarch64.AppImage

On the Pi: chmod +x <app>.AppImage && ./<app>.AppImage. An aarch64 build cannot be launched with kivyforge run on the x86_64 host. See Build for Raspberry Pi for the full guide and scope.

Quick start (Windows)

The Windows backend bundles a relocatable CPython + your win_amd64 wheels into a run-from-folder onedir: a windowed launcher .exe beside a full python-build-standalone prefix, your app source, and any declared native binaries. It needs a Windows host (the runtime is an MSVC amd64 build and the resource/signing tools are Windows-only); no compiler is required at build time.

  # 1. Add a [tool.kivy.windows] table to pyproject.toml (app_id, icons, ...)

  # 2. Resolve dependencies + pin the runtime into pylock.windows.toml
  kivyforge lock -p windows

  # 3. Build the onedir bundle (build\windows\<App>\)
  kivyforge build -p windows

  # 4a. Launch it (runs the launcher .exe in the foreground — the dev loop)
  kivyforge run -p windows

  # 4b. ...or produce the distributable (copied to dist\windows\)
  kivyforge package -p windows            # -> dist\windows\<app>-<ver>-amd64\

Double-clicking the launcher opens the app with no console flash; kivyforge run attaches it to the terminal so stdout/stderr and tracebacks are visible. The onedir folder keeps every file real and signable — installers stay external. Authenticode signing is optional and off by default: configure [tool.kivy.windows.signing] with a certificate-store thumbprint and package signs (and RFC-3161 timestamps) the launcher in the dist\windows copy.

kivyforge doctor -p windows reports environment + project health (Windows host, long-path support, app_id style, arch coverage, icon, native-binary sources/collisions/arch, build-output lock, build volume (Dev Drive advisory), reachable hosts, signtool + signing certificate).

Quick start (Android)

The Android backend assembles the official python.org Android runtime + your android_* wheels into a generated Gradle/AGP project and produces a signed .apk (sideload/CI) or .aab (Play upload) — a wheel-assembly and Gradle-drive backend, no python-for-android recipe system, no per-app C compilation. It needs a JDK, the Android SDK, and the NDK, but builds on Windows, macOS, or Linux. 64-bit only (arm64_v8a, x86_64).

  # 1. Seed [tool.kivy] + [tool.kivy.android] into pyproject.toml
  kivyforge init -p android               # then set `package`, kivy_generation, ...
  #    If your app depends on kivy or pyjnius, uncomment `extra_index_urls`
  #    in [tool.kivy.android] (see "Android wheels" below).

  # 2. Resolve dependencies + pin the runtime into pylock.android.toml
  kivyforge lock -p android

  # 3. Generate the Gradle project (<app>-android/) and assemble a debug APK
  kivyforge build -p android --debug      # -> <app>-android/app/build/outputs/apk/debug/

  # 4a. Install and launch on a connected device or emulator
  kivyforge run -p android --emulator

  # 4b. ...or produce the signed release distributable
  kivyforge package -p android            # -> <app>-android/app/build/outputs/apk/release/
  kivyforge package -p android -f aab     # -> .../outputs/bundle/release/ (Play upload)

Android wheels. Kivy has no Android wheel on PyPI, so kivyforge lock -p android fails with "pip could not resolve the Android ABI" until you point it at the first-party kivy-mobile-wheels index. kivyforge init -p android writes the line commented out; uncomment it (this is the recommended route, and needs no wheel-building):

  [tool.kivy.android]
  extra_index_urls = ["https://elliotgarbus.github.io/kivy-mobile-wheels/simple/"]

The index carries Kivy and pyjnius only. Every other dependency must already publish an android_* wheel, or you supply one in a directory listed in find_links (cross-building your own wheel). The error names the package pip could not find, so check it before changing anything else. lock uses the pip that ships inside kivyforge, not the one in your app's virtual environment.

Without --debug, step 3 stops after generating the project — ready to open in Android Studio (kivyforge open -p android) or to drive gradlew by hand.

kivy_generation = 2 targets Kivy 2.3.1 (SDL2, stable); kivy_generation = 3 targets Kivy 3.0 (SDL3, pre-release) — mutually exclusive per app, and the SDL Java glue + libSDL*.so must come from the same release (kivyforge build fails fast on a mismatch rather than the silent black-screen failure that would otherwise produce). Debug builds sign with an auto-managed debug keystore; package requires a configured release keystore ([tool.kivy.android.signing], passwords from environment variables, never in pyproject.toml).

kivyforge doctor -p android reports environment + project health (JDK/SDK/build-tools/NDK/emulator/adb, the SDL↔Kivy pairing, the pyjnius invoke0 contract, a hermetic 16 KB page-alignment scanner, ABI coverage, signing, lock-host reachability). kivyforge run --smoke runs a generated instrumented contract test on a real device/emulator — validated on an x86_64 API-31 emulator and a Pixel 8a (Android 16 / API 36) for both SDL2 and SDL3.

See the runnable examples for complete, copy-pasteable walk-throughs. They are split by runtime requirement — desktop uses Kivy 2.3.1 from PyPI, mobile resolves Kivy (2.3.1 and 3.0) from the kivy-mobile-wheels index:

Desktop (examples/desktop/) — macOS/Linux/Windows:

• dice-roller — minimal Kivy UI that builds & runs on macOS, Linux (x86_64 and Raspberry Pi), and Windows today from PyPI (Kivy 2.3.1).
• notes — Kivy app with a pure-Python dependency (platformdirs); builds on macOS, Linux, and Windows from PyPI.
• desktop-viewer — a macOS-only Kivy app (resizable window, ⌘ keyboard shortcuts, and Finder's native open panel via osascript); no Linux/Windows overlay.
• hello-native — ships non-wheel native binaries (a helper executable + a shared library) via [tool.kivy.<platform>.native.binaries]; builds and runs on macOS, Linux, and Windows (greet.dll loaded by name, roll.exe run by name).

Mobile (examples/mobile/) — iOS and Android; iOS on Kivy 3.0, Android on either generation (wheels from kivy-mobile-wheels):

iOS:

• hello-world — Kivy-free toolchain smoke test; no dependencies, no wheels (builds on iOS via the python.org Python.xcframework; the first example to bring up a new backend).
• hello-kivy — minimal Kivy 3.0 UI.
• mobile-geometry — showcases the kivy.mobile runtime-geometry API (DPI, safe-area insets, keyboard height).
• svg-explorer — interactive SVG viewer (multitouch pan/zoom/rotate).
• pyobjus-ball — calls native iOS APIs (CoreMotion, UIScreen) from Python via the Objective-C runtime.
• pyobjus-deviceinfo — reads native iOS device info (model, system version, battery) via pyobjus; a CPython 3.15 pre-release example.
• keychain-spm — declares a remote Swift Package (KeychainAccess), pins it with kivyforge lock, and calls it from Python through a local @objc shim package.

Android:

• hello-android — the smallest kivyforge Android app (a single Label); the Kivy 2.3.1 / SDL2 on-device gate.
• hello-sdl3 — the same app on Kivy 3.0 / SDL3; deliberately identical to hello-android apart from the SDL generation, and the SDL3 on-device gate.
• pyjnius-deviceinfo — reads Android device info (Build, BatteryManager, display metrics) via pyjnius, no Java written.
• qr-maven — renders a QR code with Google's ZXing, resolved as a Gradle/Maven coordinate (channel 4) and driven from Python via a pyjnius invoke0 round-trip.

Configuring your app

Your app is described declaratively in pyproject.toml. Standard PEP 621 [project] metadata supplies the name, version, and runtime dependencies; shared, platform-neutral settings live under [tool.kivy], and iOS-specific settings live under [tool.kivy.ios] (each other platform has its own [tool.kivy.<platform>] table — macos, linux, windows, android):

[project]
name = "hello-world"
version = "0.1.0"
requires-python = ">=3.15.0b4"
dependencies = []                       # PyPI/local deps resolved into the lockfile

[tool.kivy]
display_name = "Hello World"            # name shown under the icon
app_dir = "src"                         # folder containing your Python source
entry_point = "main"                    # module run as __main__ at launch (main.py)
orientation = ["portrait"]

[tool.kivy.ios]
bundle_id = "org.example.hello-world"   # reverse-DNS; UTI characters only (no underscores)
build = 1
deployment_target = "16.0"
# find_links = ["../../wheels/ios"]     # repo-relative wheel directory for lock
# exclude = ["docutils", "pygments"]    # drop transitive deps you don't use at runtime

[tool.kivy.ios.python]
version = "3.15.0b4"                     # python.org Python.xcframework version

[tool.kivy.ios.signing]
team_id = ""                            # Apple Developer Team ID (device / release builds)
identity = "Apple Development"
auto_signing = true

kivyforge build syncs your app_dir into the generated <app>-ios/ tree on every run, so make changes in your source folder (e.g. src/), never in the generated project.

Kivy's wheel declares dependencies that are not all needed at runtime on iOS. The exclude list trims them; the hello-kivy example documents what each one is for, so you can re-enable only the few that map to widgets you actually use (e.g. docutils for RSTDocument, pygments for CodeInput, or requests for UrlRequest).

Commands

The verbs are platform-neutral; each resolves a target from -p/--platform, the KIVYFORGE_PLATFORM environment variable, or the host default, and then does the platform's version of the same job. init is the one exception: -p is repeatable there (-p ios -p android), since seeding several platforms into one pyproject.toml is its normal use case — every other verb builds, runs, or packages exactly one target per invocation.

  kivyforge init       Seed [tool.kivy] + the target's overlay into pyproject.toml
  kivyforge lock       Generate pylock.<platform>.toml from pyproject.toml
  kivyforge build      Download artifacts, generate the native project, build
  kivyforge run        Build (unless --no-build), install, and launch the app
  kivyforge package    Produce the signed, distributable artifact
  kivyforge open       Open the generated project in Xcode / Android Studio
  kivyforge status     Show app identity, Python version, lock sync, build state
  kivyforge clean      Remove generated artifacts in the project folder
  kivyforge upgrade    Re-fetch the pinned runtime and native artifacts
  kivyforge doctor     Run environment and project health checks

Run kivyforge <command> -h (or kf <command> -h) for the full set of options on any verb. A few common ones:

• kivyforge init -p ios -p android — seed several platforms' overlays in one run.
• kivyforge lock --check — CI pre-flight; exits non-zero if the lock is stale.
• kivyforge build --simulator | --device | --release (iOS) — pick the build flavor.
• kivyforge build --debug [--abi arm64_v8a|x86_64] (Android) — assemble a debug APK, optionally for one ABI.
• kivyforge run --list-devices — list available simulators/emulators and devices.
• kivyforge run --smoke (Android) — run the generated on-device contract test.
• kivyforge run --release (Android, Linux, macOS, Windows) — build and launch the release flavor, to exercise byte_compile/strip_source outside of package.
• kivyforge clean --cache — also flush the artifact download cache.

Downloaded artifacts (Python.xcframework, the per-ABI Android runtime, .aar/.jars, runtime archives) are cached per-user and shared across projects.

Every verb but run also takes --json, for scripting or driving kivyforge from an agent — see Working with agents below.

Typical workflow

A normal session is a one-time setup followed by a tight edit → run loop. You only re-run kivyforge lock when dependencies change, and kivyforge build when you change app config (or need to regenerate the native project).

How cheap the inner loop is depends on the platform. On iOS the generated project links your source directory (app/ is a symlink to app_dir), so editing Python source needs no rebuild — just relaunch. On Android the app's code is packed into the APK's asset bundle, so a source edit needs a re-pack: kivyforge run does that for you every iteration, which is why the Android loop goes through run rather than a bare relaunch.

flowchart TD
    A["kivyforge init<br/>seed pyproject.toml"] --> B["Edit pyproject.toml<br/>dependencies + app config"]
    B --> C["Write your app<br/>src/main.py"]
    C --> D["kivyforge lock<br/>→ pylock.&lt;platform&gt;.toml"]
    D --> E["kivyforge build<br/>fetch artifacts + generate the native project"]
    E --> F{"Launch it"}
    F -->|from the CLI| G["kivyforge run<br/>--simulator / --emulator / --device"]
    F -->|from the IDE| H["kivyforge open → Xcode ⌘R / Android Studio Run"]
    G --> I(["Iterate"])
    H --> I
    I -->|changed Python source| F
    I -->|changed app config| E
    I -->|changed dependencies| D

Supporting commands fit around this loop: kivyforge status shows whether your lock and build are current, kivyforge doctor diagnoses environment problems, kivyforge upgrade re-fetches the pinned runtime, and kivyforge clean resets the generated project when you want a fresh build.

Working with agents

kivyforge is designed to also be driven non-interactively — by CI, or by an agent (Claude Code and similar) building or maintaining a Kivy app on your behalf. No verb prompts for input, and every verb but run accepts --json.

• Discover capabilities first: kivyforge capabilities --json lists every platform, its architectures and package formats, which hosts can build which targets, every verb and whether it takes --json, and the exit-code and KF-* diagnostic-code vocabularies. It needs no project, lock, or network access, so it's the right first call before touching a real project.
• --json puts exactly one envelope on stdout — {"schema", "kivyforge", "command", "platform", "ok", "data", "diagnostics"} — on success and on every failure. Progress and log lines go to stderr, so a build log and a parseable result coexist on the same run.
• Branch on the exit code first, then diagnostics[].code: 1 — fix pyproject.toml; 2 — a bad flag (click's own usage error; kivyforge never raises it); 3 — fix the machine (missing toolchain); 4 — the lock is stale, re-run kivyforge lock; 5 — a build genuinely failed, read the log on stderr. The code is a stable contract; the human-readable message next to it is not, and may be reworded across releases.
• diagnostics on an ok: true run are warnings, not failures — an unsigned package, a byte-compile that silently degraded to shipping source, a resolver policy note. Read them; don't treat ok: true as "nothing to look at."
• Build/package outputs are data.artifacts, as {"path", "kind"} pairs relative to the project root, always posix-spelled — read that instead of guessing the layout, and only trust artifacts a run reports for itself: a failed run's artifacts never names a stale file left over from a previous one.
• run is the one verb without --json. It hands your app's own process the console directly (stdout/stderr pass through untouched), which is the point of the verb; script against build/package plus status --json instead.

Development

Clone the repository and install it into a virtual environment:

  git clone https://github.com/ElliotGarbus/kivyforge.git
  cd kivyforge/
  python3 -m venv .venv
  . .venv/bin/activate
  pip install -e ".[dev]"

Run the test suite and the linter:

  pytest
  ruff check .

FAQ

For troubleshooting advice and other frequently asked questions, consult the latest kivyforge FAQ.

License

kivyforge is MIT licensed, and builds on work actively developed by a great community and supported by many projects managed by the Kivy Organization.

Support

Are you having trouble using kivyforge or any of its related projects in the Kivy ecosystem? Is there an error you don’t understand? Are you trying to figure out how to use it? We have volunteers who can help!

The best channels to contact us for support are listed in the latest Contact Us document.

Contributing

kivyforge builds on the Kivy ecosystem - a large group of products used by many thousands of developers for free, but it is built entirely by the contributions of volunteers. We welcome (and rely on) users who want to give back to the community by contributing to the project.

Contributions can come in many forms. See the latest Contribution Guidelines for how you can help us.

Code of Conduct

In the interest of fostering an open and welcoming community, we as contributors and maintainers need to ensure participation in our project and our sister projects is a harassment-free and positive experience for everyone. It is vital that all interaction is conducted in a manner conveying respect, open-mindedness and gratitude.

Please consult the latest Kivy Code of Conduct.

Contributors

This project exists thanks to all the people who contribute. [Become a contributor].

Backers

Thank you to all of our backers! 🙏 [Become a backer]

Sponsors

Special thanks to all of our sponsors, past and present. Support this project by [becoming a sponsor].

Here are our top current sponsors. Please click through to see their websites, and support them as they support us.