Briefcase Documentation

Briefcase is a tool for converting a Python project into a standalone native application. It supports packaging projects for the following platforms:

• Mac
• Windows
• Linux
• iPhone/iPad
• Android
• Web

Support for AppleTV, watchOS, and wearOS deployments is planned.

Briefcase is a tool used to convert Python projects into standalone native applications. It supports packaging applications for the following platforms:

• macOS: Standalone .app bundles.
• Windows: MSI installers.
• Linux: Native system packages.
• iOS: Xcode projects.
• Android: Gradle projects.
• Web: Static websites using PyScript for client-side Python.

Briefcase is extensible, allowing for the creation of additional platforms and installation formats.

Briefcase provides an AppImage backend using linuxdeploy to package Linux applications.

Warning: Briefcase strongly discourages using AppImages for GUI application distribution due to significant issues with binary wheels, older base images, DBus integration, and libraries like WebKit2.

Recommended Alternatives: For more reliable Linux distribution, use System packages or Flatpaks.

AppImages are designed to run on most Linux distributions by containing necessary dependencies, provided the target system's libc version is greater than or equal to the version used during the build.

Briefcase supports various build workflows and application types:

• CI with GitHub Actions: Use the provided workflow to test, build, and package projects for Windows, Linux, macOS, iOS, and Android in a continuous integration environment.
• Console Apps: Follow specific steps for creating console-based applications instead of GUI-based apps.
• External Apps: Use Briefcase to package applications that were originally constructed using a different tool.

Before creating a certificate on Apple's website, you must generate a request file on your Mac:

1. Open Keychain Access.
2. Navigate to Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority.
3. In the Certificate Assistant window:
   • User Email Address: Enter your Apple Developer Account email.
   • Common Name: Enter the name used for your Apple Developer registration.
   • CA Email Address: Leave empty.
   • Request is: Select Saved to Disk.
4. Click Continue and save the file (it will have a .certSigningRequest extension).

Note: This process also creates a private key in your Keychain, which is required to validate the certificate later.

Wizard templates are used by briefcase new to generate the initial project layout. You can test custom wizard templates without modifying Briefcase core by specifying a local path or a remote GitHub repository and branch using the --template and --template-branch flags.

To test a local fork:

1. Clone the template repository.
2. Run briefcase new pointing to the local directory.

To test a remote fork:

1. Push your changes to GitHub.
2. Run briefcase new pointing to your GitHub URL and specifying the branch.

To create a terminal-based application instead of a GUI application, use briefcase new and select the Console option when prompted for a GUI framework.

Selecting Console adds the console_app = true flag to your pyproject.toml. This informs Briefcase that the application is a non-GUI, terminal-based app that prints directly to stdout/stderr.

$ briefcase new
...
-- GUI Framework -------------------------------------------------------------

What GUI toolkit do you want to use for this project?

Additional GUI bootstraps are available from the community.

Check them out at https://beeware.org/bee/briefcase-bootstraps

1) Toga
2) PySide6 (does not support iOS/Android/Web deployment)
3) Pygame  (does not support iOS/Android/Web deployment)
4) Console (does not support iOS/Android/Web deployment)
5) None

GUI Framework [1]: 4

To package applications for macOS using Briefcase, ensure you have the following installed:

• Python 3.10+
• A method for managing virtual environments (e.g., venv).

Console applications can be packaged for Linux, Windows, and macOS. Note that console apps cannot be deployed to Android, iOS, or the Web as those platforms do not provide a user-accessible console.

macOS Specifics: Console apps on macOS are packaged as .pkg installers rather than .app or .dmg bundles. This ensures the binary is correctly placed on the user's path for command-line execution.

Executable Name: The command used to run the app in the terminal is the app name (e.g., hello-cli), not the formal name (e.g., Hello CLI).

$ briefcase create
$ briefcase build
$ briefcase package

You can use any third-party package available on PyPI or via a local wheel file by adding it to the requires list in your pyproject.toml file. Briefcase uses pip to install these into your app bundle.

Requirements for Binary Components

If a package contains binary components, you must ensure a binary wheel is available for your target platform:

• macOS, Linux, Windows: Use wheels hosted on PyPI.
• Android: Follow the specific Android platform documentation.
• iOS: Follow the specific iOS platform documentation.
• Web: Support is limited to wheels provided by the Pyodide project.