buildozer

Generic Python packager for Android and iOS

1,812

533

1,812

105

View on GitHub

Top Related Projects

pipenv

25,068

Python Development Workflow for Humans.

pyinstaller

12,326

Freeze (package) Python programs into stand-alone executables

briefcase

2,863

Tools to support converting a Python project into a standalone native application.

flit

2,208

Simplified packaging of Python modules

Quick Overview

Buildozer is an open-source tool designed to package mobile applications written in Python using the Kivy framework. It automates the process of creating Android and iOS applications from Python code, handling dependencies, and generating the necessary build files.

Pros

Simplifies the process of creating mobile apps from Python code
Supports both Android and iOS platforms
Handles dependencies and build configurations automatically
Integrates well with the Kivy framework for cross-platform development

Cons

Limited to Python and Kivy-based applications
May require additional setup for complex projects or custom native modules
Documentation can be sparse for advanced use cases
Build process can be slow, especially for initial builds

Getting Started

Install Buildozer:

pip install buildozer

Initialize Buildozer in your project directory:

buildozer init

Edit the buildozer.spec file to configure your app settings.
Build your Android app:

buildozer android debug

For iOS builds, you'll need to use a Mac and have Xcode installed:

buildozer ios debug

Note: iOS builds require additional setup and an Apple Developer account.

Competitor Comparisons

pipenv

25,068

Python Development Workflow for Humans.

Pros of pipenv

Manages both dependencies and virtual environments in a single tool
Provides a lockfile for deterministic builds and dependency resolution
Integrates well with Python packaging ecosystem and PyPI

Cons of pipenv

Can be slower than other package managers for large projects
Sometimes encounters compatibility issues with certain packages
Learning curve for users familiar with traditional pip and virtualenv

Code comparison

Pipenv:

# Pipfile
[packages]
requests = "*"
flask = "==1.1.2"

# Install dependencies
$ pipenv install

Buildozer:

# buildozer.spec
requirements = requests,flask==1.1.2

# Build Android app
$ buildozer android debug

Pipenv focuses on Python package management and virtual environments, while Buildozer is specifically designed for building mobile applications using Kivy. Pipenv offers more granular control over dependencies and provides a lockfile for reproducibility. Buildozer, on the other hand, simplifies the process of packaging Python applications for mobile platforms, handling not only dependencies but also the entire build process for Android and iOS.

pyinstaller

12,326

Freeze (package) Python programs into stand-alone executables

Pros of PyInstaller

Supports a wide range of Python libraries and frameworks
Creates standalone executables for multiple platforms (Windows, macOS, Linux)
Extensive documentation and active community support

Cons of PyInstaller

Limited mobile platform support (primarily desktop-focused)
May require manual configuration for complex dependencies
Larger executable sizes compared to some alternatives

Code Comparison

Buildozer

# buildozer.spec
[app]
title = MyApp
package.name = myapp
source.dir = .
requirements = kivy

PyInstaller

# myapp.spec
a = Analysis(['main.py'],
             pathex=['/path/to/your/app'],
             hiddenimports=[],
             hookspath=[],
             runtime_hooks=[],
             excludes=[],
             win_no_prefer_redirects=False,
             win_private_assemblies=False,
             cipher=None)

Key Differences

Buildozer is specifically designed for Kivy applications and mobile deployment
PyInstaller offers broader support for various Python projects and desktop platforms
Buildozer provides a more streamlined experience for mobile app packaging
PyInstaller requires more manual configuration but offers greater flexibility for desktop applications

briefcase

2,863

Tools to support converting a Python project into a standalone native application.

Pros of Briefcase

Supports multiple GUI frameworks (not just Kivy)
Provides a more streamlined development workflow
Better documentation and community support

Cons of Briefcase

Less mature and potentially less stable than Buildozer
May have fewer platform-specific optimizations
Steeper learning curve for beginners

Code Comparison

Buildozer (specfile):

[app]
title = MyApp
package.name = myapp
source.dir = .
requirements = kivy

Briefcase (pyproject.toml):

[tool.briefcase.app.myapp]
formal_name = "MyApp"
description = "My amazing app"
sources = ["src/myapp"]
requires = ["toga"]

Both tools aim to simplify the process of packaging Python applications for various platforms, but they differ in their approach and supported frameworks. Buildozer is specifically designed for Kivy applications, while Briefcase supports multiple GUI frameworks, including Toga.

Briefcase offers a more modern development experience with better documentation and community support. However, Buildozer has been around longer and may be more stable for Kivy-specific projects.

The code comparison shows the different configuration approaches: Buildozer uses a specfile, while Briefcase uses pyproject.toml for project configuration.

flit

2,208

Simplified packaging of Python modules

Pros of Flit

Simpler and more lightweight tool focused on packaging Python modules
Supports modern Python packaging standards like PEP 517 and PEP 518
Easier to use for pure Python projects with minimal dependencies

Cons of Flit

Limited support for complex build processes or non-Python dependencies
Not designed for mobile app development or cross-platform compilation
Less suitable for projects with extensive native extensions or C libraries

Code Comparison

Flit configuration (pyproject.toml):

[build-system]
requires = ["flit_core >=3.2,<4"]
build-backend = "flit_core.buildapi"

[project]
name = "example"
version = "0.1.0"
description = "An example package"

Buildozer configuration (buildozer.spec):

[app]
title = MyApp
package.name = myapp
source.dir = .
requirements = kivy,python3

[buildozer]
log_level = 2
warn_on_root = 1

Flit is more focused on Python packaging, while Buildozer is tailored for mobile app development, particularly with Kivy. Flit uses modern Python packaging standards, whereas Buildozer provides a more comprehensive build system for cross-platform mobile applications.

pants

3,481

The Pants Build System

Pros of Pants

More comprehensive build system supporting multiple languages and platforms
Highly scalable for large codebases and monorepos
Extensive plugin ecosystem for customization

Cons of Pants

Steeper learning curve due to its complexity
May be overkill for smaller projects or single-platform applications
Requires more setup and configuration compared to Buildozer

Code Comparison

Buildozer (simple Android app configuration):

[app]
title = My App
package.name = com.example.myapp
source.dir = .
requirements = kivy

Pants (basic Python project configuration):

python_sources(
    name="my_app",
    sources=["**/*.py"],
)

python_distribution(
    name="dist",
    dependencies=[":my_app"],
    provides=setup_py(
        name="my_app",
        version="1.0.0",
    ),
)

Buildozer focuses on simplifying Android app packaging for Kivy projects, while Pants offers a more comprehensive build system for various languages and platforms. Buildozer is easier to set up for mobile app development, but Pants provides greater flexibility and scalability for larger, multi-language projects.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Buildozer

Buildozer is a development tool for turning Python applications into binary packages ready for installation on any of a number of platforms, including mobile devices.

The app developer provides a single "buildozer.spec" file, which describes the application's requirements and settings, such as title and icons. Buildozer can then create installable packages for Android, iOS, Windows, macOS and/or Linux.

Buildozer is managed by the Kivy Team. It relies on its sibling projects: python-for-android and Kivy for iOS. It has features to make building apps using the Kivy framework easier, but it can be used independently - even with other GUI frameworks.

For Android, buildozer will automatically download and prepare the build dependencies. For more information, see Android SDK NDK Information.

[!NOTE] This tool is unrelated to the online build service, buildozer.io.

PyPI - Version PyPI - Python Version

Installation

Buildozer

Installing Buildozer with target Python 3 (default):

Buildozer incorporates a number of technologies, and has a complicated dependencies, including platform dependencies outside of Python.

This means installation is more than a simple pip install; many of our support requests are related to missing dependencies.

So, it is important to follow the instructions carefully.

Please see the Installation documentation specific to this version.

Buildozer Docker image

A Dockerfile is available to use buildozer through a Docker environment.

Build with:

docker build --tag=kivy/buildozer .

For macOS, build with:

docker buildx build --platform=linux/amd64 --tag=kivy/buildozer .

Run with:

docker run --volume "$(pwd)":/home/user/hostcwd kivy/buildozer --version

Example Build with Caching

Build and keep downloaded SDK and NDK in ~/.buildozer directory:

docker run -v $HOME/.buildozer:/home/user/.buildozer -v $(pwd):/home/user/hostcwd kivy/buildozer android debug

The image is published to both Docker Hub and GitHub Container Registry and can be pulled from both:

docker pull kivy/buildozer:latest
docker pull ghcr.io/kivy/buildozer:latest

Buildozer GitHub action

Use ArtemSBulgakov/buildozer-action@v1 to build your packages automatically on push or pull request. See full workflow example.

Usage

Usage:
    buildozer [--profile <name>] [--verbose] [target] <command>...
    buildozer --version

Available targets:
    android        Android target, based on python-for-android project
    ios            iOS target, based on kivy-ios project

Global commands (without target):
    distclean          Clean the whole Buildozer environment
    help               Show the Buildozer help
    init               Create an initial buildozer.spec in the current directory
    serve              Serve the bin directory via SimpleHTTPServer
    setdefault         Set the default command to run when no arguments are given
    version            Show the Buildozer version

Target commands:
    clean      Clean the target environment
    update     Update the target dependencies
    debug      Build the application in debug mode
    release    Build the application in release mode
    deploy     Deploy the application on the device
    run        Run the application on the device
    serve      Serve the bin directory via SimpleHTTPServer

Target "ios" commands:
    list_identities    List the available identities to use for signing.
    xcode              Open the xcode project.

Target "android" commands:
    adb                Run adb from the Android SDK. Args must come after --, or
                        use --alias to make an alias
    logcat             Show the log from the device
    p4a                Run p4a commands. Args must come after --, or use --alias
                        to make an alias

Examples of Buildozer commands

# buildozer target command
buildozer android clean
buildozer android update
buildozer android deploy
buildozer android debug
buildozer android release

# or all in one (compile in debug, deploy on device)
buildozer android debug deploy

# set the default command if nothing set
buildozer setdefault android debug deploy run

`buildozer.spec`

Run buildozer init to have a new buildozer.spec file copied into the current working directory. Edit it before running your first build.

See buildozer/default.spec for the template.

Default config

You can override the value of any buildozer.spec config token by setting an appropriate environment variable. These are all of the form $SECTION_TOKEN, where SECTION is the config file section and TOKEN is the config token to override. Dots are replaced by underscores.

For example, here are some config tokens from the [app] section of the config, along with the environment variables that would override them.

title -> $APP_TITLE
package.name -> $APP_PACKAGE_NAME
p4a.source_dir -> $APP_P4A_SOURCE_DIR

License

Buildozer is MIT licensed, actively developed by a great community and is supported by many projects managed by the Kivy Organization.

Documentation

Documentation for this repository.

Support

Are you having trouble using Buildozer 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

Buildozer is part of 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 Code of Conduct.