Skip to content

Briefcase

by Tim Hopper
Packaging

Briefcase is the only mainstream Python packaging tool that ships to iOS and Android. It also packages applications for macOS, Windows, Linux, and the Web, producing platform-specific artifacts (.app/DMG, MSI, .deb/.rpm/AppImage/Flatpak, Xcode project, Gradle project, PyScript/Pyodide site) from a single pyproject.toml configuration.

Briefcase is part of the BeeWare project and is the packaging companion to Toga, BeeWare’s cross-platform GUI toolkit. Briefcase does not require Toga; it packages any Python application, GUI or otherwise. Install it with uv tool install briefcase or pipx install briefcase; the BSD 3-Clause license imposes no restrictions on applications it packages.

Key Features

  • Targets macOS, Windows, Linux, iOS, Android, and the Web from one project definition.
  • Produces platform-specific artifacts: .app or DMG on macOS, MSI on Windows, .deb/.rpm/AppImage/Flatpak on Linux.
  • Generates an Xcode project for iOS and a Gradle project for Android that can be opened in the respective IDEs and submitted to the App Store or Google Play.
  • Uses pyproject.toml under a [tool.briefcase] table for all configuration.
  • Ships a plugin system for adding new platforms and installer formats.
  • Scaffolds new projects interactively through briefcase new.

How Briefcase Works

A Briefcase project declares application metadata in pyproject.toml under the [tool.briefcase] table. A minimal configuration names the project, a reverse-DNS bundle identifier, and each app’s sources:

[tool.briefcase]
project_name = "My Project"
bundle = "com.example"
version = "0.1"

[tool.briefcase.app.myapp]
formal_name = "My App"
description = "My first Briefcase App"
sources = ["src/myapp"]

The Briefcase CLI drives the build pipeline through ten top-level subcommands:

Command Purpose
briefcase new Scaffold a new project interactively
briefcase dev Run the app against the local Python environment for fast iteration
briefcase create Generate the platform scaffold (Xcode project, Gradle project, .app skeleton, etc.)
briefcase build Compile the scaffold into a runnable binary
briefcase run Launch the built artifact on device or simulator
briefcase update Refresh app source and resources inside an existing scaffold
briefcase package Produce the distributable installer or store-ready bundle
briefcase publish Upload a packaged app to its store or distribution channel
briefcase convert Convert an existing Python project into a Briefcase project
briefcase upgrade Update the Briefcase-managed support tooling

Most build and packaging commands accept a platform argument (for example briefcase build iOS), so one project can target multiple platforms from the same source tree.

Mobile Platform Support

No other mainstream Python packaging tool produces App Store or Google Play submissions from a Python codebase. Briefcase’s iOS and Android support relies on prebuilt Python interpreter binaries and mobile-specific binary wheels that BeeWare maintains, not on PyPI’s general wheel set.

Pure-Python dependencies work anywhere. Dependencies with C extensions work on desktop via the wheels PyPI already hosts, and on mobile only if a compatible binary wheel exists for that target. On iOS and Android, packages with compiled code require a binary wheel built for that platform, and scientific or machine-learning dependencies such as NumPy, PyTorch, or SciPy are often unavailable or lag behind their desktop counterparts. The Web target uses Pyodide’s wheel set and inherits its limitations.

Briefcase is pre-1.0 (0.4.1). BeeWare uses Briefcase for its own Toga applications. Support for tvOS, watchOS, and WearOS is listed on the BeeWare roadmap but is not yet a shipping target.

Pros

  • Ships to iOS and Android, which no other mainstream Python packaging tool does.
  • Produces platform-specific artifacts such as MSI, DMG, AppImage, Flatpak, Xcode projects, and Gradle projects.
  • Uses one [tool.briefcase] table in pyproject.toml for every target platform.
  • Supports new platforms and installer formats through plugins.
  • Uses the BSD 3-Clause license and remains under active development.

Cons

  • Remains pre-1.0 at version 0.4.1.
  • Depends on BeeWare-maintained binary wheels for mobile packages with compiled code.
  • Cannot package many C-extension and ML dependencies on mobile targets.
  • Inherits Pyodide’s package limits on the Web target.
  • Faces more established competition on desktop-only targets from PyInstaller, Nuitka, and cx_Freeze.

Learn More

Last updated on
Blackbuild

Please submit corrections and feedback...