# Briefcase


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](https://beeware.org) project and is the packaging companion to [Toga](https://toga.readthedocs.io/), 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:

```toml
[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.2). 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.2.
- 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](https://pydevtools.com/handbook/reference/pyinstaller.md), [Nuitka](https://pydevtools.com/handbook/reference/nuitka.md), and [cx_Freeze](https://pydevtools.com/handbook/reference/cx-freeze.md).

## Learn More

- [Briefcase documentation](https://briefcase.readthedocs.io/)
- [BeeWare project](https://beeware.org)
- [Briefcase GitHub repository](https://github.com/beeware/briefcase)
- [Toga, the BeeWare GUI toolkit](https://toga.readthedocs.io/)
- [PyScript](https://pyscript.net/), used for the Web target
- [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md) describes the configuration file Briefcase reads
- [How do I ship a Python application to end users?](https://pydevtools.com/handbook/explanation/how-do-i-ship-a-python-application-to-end-users.md) compares Briefcase with the desktop-only freezers