Skip to content

Install kivyforge

kivyforge is a command-line tool. This page installs it and confirms that it runs. It does not install the per-target toolchains (Xcode, the Android SDK, and so on). Each platform guide covers those.

Before you begin

  • Python 3.13 or newer. If you install with uv and have no suitable Python, uv downloads one for you.
  • One of these installers: uv (recommended), pipx, or pip.

kivyforge is in pre-release

Every kivyforge release on PyPI so far is a pre-release (a version such as 3.0.0.dev1). pipx and pip skip pre-releases unless you ask for them, so their commands below include a pre-release flag. uv installs a pre-release when a package has no stable release, so its commands need no flag. Once a stable release is published, the flags are no longer needed.

uv installs command-line tools into their own isolated environment and puts them on your PATH, so kivyforge works from any directory without you managing a virtual environment.

uv tool install kivyforge

If your shell reports that kivyforge is not found, uv's tool directory is not on your PATH yet. Add it, then open a new terminal:

uv tool update-shell

To upgrade or remove the tool later:

uv tool upgrade kivyforge
uv tool uninstall kivyforge

Install with pipx

pipx also installs command-line tools into isolated environments:

pipx install --pip-args="--pre" kivyforge

To upgrade later, keep the flag:

pipx upgrade --pip-args="--pre" kivyforge

Install with pip

If you use neither uv nor pipx, install kivyforge into a virtual environment so it does not collide with other projects:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install --pre kivyforge

python3 -m venv .venv
source .venv/bin/activate
pip install --pre kivyforge

With this method, kivyforge is available only while the virtual environment is active.

Verify

Check the version and ask the tool what it can do:

kivyforge --version
kivyforge capabilities

kivyforge capabilities needs no project, lock, or network. It prints the targets, their architectures and package formats, and which hosts can build which targets.

The kf alias

The install also adds a kf command, so kf build -p linux is the same as kivyforge build -p linux. This documentation uses the full name.

Per-host prerequisites

Each target needs its own toolchain on the build host. Install these when you start building for a target:

To check whether this host is ready for a target, run doctor:

kivyforge doctor -p PLATFORM

Replace PLATFORM with android, ios, macos, linux, or windows. For the full host matrix, see Which host builds which target.

What's next