# Briefcase: packaging a Python project as a native app for desktop, mobile and web

> BeeWare's Briefcase turns a Python project into a standalone native application for Mac, Windows, Linux, iOS, Android and the web. It is a build orchestrator, not a bundler, and its platform support is uneven by design.

**beeware/briefcase** — Tools to support converting a Python project into a standalone native application.

- Repository: https://github.com/beeware/briefcase
- Website: https://briefcase.beeware.org/
- Stars: 3,349 · Forks: 550
- Language: Python
- License: BSD-3-Clause
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/beeware-briefcase

## What Briefcase solves, and who it is actually for

Python ships code well and ships applications badly. A wheel installs a library into someone else's interpreter; it does not produce a .app bundle, an .msi, a .deb, an .apk or an installable web page. Briefcase exists to close that gap. The README describes it as "a tool for converting a Python project into a standalone native application", and the pyproject.toml description repeats that wording verbatim.

The intended audience is a developer with an existing Python project who wants one codebase to reach several targets. The README lists Mac, Windows, Linux, iPhone/iPad, Android and Web, and states that support for AppleTV, watchOS and wearOS deployments is planned. That last sentence matters more than it looks: it tells you the project is deliberately incomplete on the Apple side of the matrix, and it tells you the maintainers publish the gaps rather than hiding them.

Briefcase is not a general-purpose installer generator, and it is not aimed at people packaging a single script for one operating system. Its value appears when the same project has to produce several different artifacts, because the per-platform work is where the duplication lives.

## How Briefcase works: scaffolding, not a bundler

The mechanism is generation plus orchestration. Briefcase creates a platform-specific project skeleton around your code, then drives the native toolchain for that platform to build the artifact. The repository layout reflects that split: src/ holds the package, automation/ holds separate tooling, and tests/ sits alongside them. The pyproject.toml keywords name the outputs directly, including flatpak, appimage, deb, rpm, pkg, pyscript and pyodide. Those are not abstractions; they are the concrete formats the tool is expected to emit.

That design has a consequence worth stating plainly. Because Briefcase generates scaffolding, the generated files become part of your repository, and you own them. When a platform changes its requirements, the upgrade path runs through regenerating and reconciling that scaffolding rather than through a single version bump. The README does not document a rollback procedure for a build that breaks after an upgrade, and the changelog directory (changes/) is where release notes accumulate rather than a migration guide.

There is also a hard environment constraint. Building for iOS or Android requires that platform's SDK and toolchain on the machine doing the build. Briefcase orchestrates those tools; it does not replace them. A Linux container cannot produce a signed iOS build on its own.

## Installing Briefcase and running a first build

The README gives exactly one installation command, and it installs from PyPI:

```bash
python -m pip install briefcase
```

After that, the interpreter has a briefcase entry point. The README points to the BeeWare tutorial at tutorial.beeware.org for a full introduction, and describes it as walking you through creating and packaging a new application. That tutorial is the documented starting point; the README itself does not reproduce the per-platform build commands.

What the repository does tell you is the Python floor. The pyproject.toml sets requires-python to ">= 3.11", and the classifiers list 3.11 through 3.15. If your project still supports 3.10 or earlier, the interpreter running Briefcase is a separate concern from the interpreter your app targets, but you cannot install Briefcase itself on an older runtime.

One more thing visible in the packaging metadata: the build backend is setuptools with setuptools==84.0.0 and setuptools_scm==10.2.3 pinned exactly, with a comment noting the versions are kept in sync with automation/pyproject.toml. That is a deliberate choice to keep the build reproducible, and it is the kind of detail that matters if you build Briefcase from source rather than installing the wheel.

## Where Briefcase is the wrong tool

The most honest limitation is the one in the classifiers: Development Status :: 4 - Beta. That is the project's own label, not an outsider's assessment. A beta packaging tool means you should expect generated scaffolding to change between releases, and you should pin the version you build with rather than tracking the latest.

Second, cross-compilation is not the model. Briefcase drives native toolchains, so a Mac build wants macOS, a Windows build wants Windows, and mobile builds want the relevant SDK. If your release process assumes one Linux CI runner produces every artifact, Briefcase will not fit that shape without additional machines or runners.

Third, the platform list is a promise about intent, not a guarantee of parity. The README says AppleTV, watchOS and wearOS are planned. Anything not on the supported list is not something you can ship with this tool today, and the README does not offer a workaround.

Finally, if your deliverable is a Python library rather than an application, Briefcase solves a problem you do not have. A wheel and a normal build backend will get you further with less machinery.

## Briefcase compared with PyInstaller and Nuitka

The obvious alternative for desktop packaging is PyInstaller, and the difference in approach is fundamental rather than cosmetic. PyInstaller freezes an existing Python program into a single executable or a folder: it inspects your imports, collects the dependencies, and bundles an interpreter with them. You point it at an entry script and it produces output. There is no project skeleton, no per-platform source tree, and no notion of a mobile target.

Briefcase works the other way around. It starts from a project structure, generates platform-specific scaffolding, and then invokes the native toolchain for the target. That is heavier, and it asks more of your repository, but it is what makes iOS and Android reachable at all. PyInstaller's freezing model has no path to an .apk or an .ipa.

Nuitka sits closer to a compiler: it translates Python to C and builds a binary, trading build time for runtime characteristics. Briefcase does not compile your code in that sense; it packages it and hands it to the platform's own build system.

So the choice is not which tool is better. It is whether you need multiple platforms, including mobile, from one project. If you need one desktop executable, PyInstaller is the smaller commitment. If you need a Mac app and an Android app from the same code, Briefcase is the tool whose model matches the problem.

## Maintenance, licence and the cost of upgrading

Briefcase is BSD-3-Clause, and the licence text is shipped in the repository root as LICENSE, with license-files listing it in pyproject.toml and the SPDX identifier "BSD-3-Clause" set in the project metadata. A permissive licence of that kind generally allows commercial and closed-source use, but the terms that apply to you are the ones in the file, and reading it is your job rather than a summary's.

The maintenance picture is concrete. The repository is not archived, and the last push was on 2026-07-08, which is the same timestamp as the v0.4.4 release. Two releases landed in the week before that (v0.4.3 on 2026-07-02) and one earlier (v0.4.2 on 2026-05-06). That cadence suggests a project that ships fixes at short notice, which cuts both ways: you get corrections quickly, and you also get a moving target.

Upgrade cost is where the design bites. Because Briefcase generates per-platform scaffolding, a release that changes how the scaffolding is produced can require you to reconcile generated files in your own repository. The README does not document a rollback path, and the changes/ directory is a changelog rather than a migration guide. Budget for reading release notes before bumping the pin, and for keeping the previous version available if a platform build regresses.

Financial support is worth noting for anyone making a long-term bet. The README names Anaconda Inc. as a financial member and points to a membership page for individual contributions, which is the project's stated funding model.

## Conclusion

Adopt Briefcase if you are shipping one Python codebase to desktop and mobile and you are willing to let it generate and own per-platform scaffolding. Do not adopt it if you need a fully offline, air-gapped build, if you target AppleTV, watchOS or wearOS today (the README lists those as planned), or if you cannot keep a working toolchain for every platform you ship to. Before committing, verify three things: the classifiers mark the project Development Status 4 - Beta, so pin the briefcase version you build with; the README documents no rollback path for an upgrade that breaks a platform build; and requires-python is >= 3.11, so confirm your own project's floor matches.

## FAQ

### How do I install Briefcase?

The README gives one command: python -m pip install briefcase. That installs it from PyPI, and the README points to the BeeWare tutorial for a full introduction to using it.

### What is Briefcase?

Briefcase is a tool for converting a Python project into a standalone native application, according to the README. It can package projects for Mac, Windows, Linux, iPhone/iPad, Android and Web.

### Which platforms can Briefcase package a Python project for?

The README lists Mac, Windows, Linux, iPhone/iPad, Android and Web. It also states that support for AppleTV, watchOS and wearOS deployments is planned.

### What Python version does Briefcase require?

The pyproject.toml sets requires-python to ">= 3.11", and the classifiers list Python 3.11 through 3.15. Older interpreters cannot install it.

### Is Briefcase stable enough to ship with?

The project classifies itself as Development Status :: 4 - Beta. That is the project's own label, and it is the reason to pin the version you build with rather than tracking the latest release.

## Sources

- [Official documentation](https://briefcase.beeware.org/)
- [Official README](https://github.com/beeware/briefcase#readme)
- [Project repository](https://github.com/beeware/briefcase)
- [Release notes](https://github.com/beeware/briefcase/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/beeware-briefcase