BRIEFCASE(1)

📦 version 0.4.1, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, gather round 🫶 — briefcase is the tool for converting Python projects into standalone native applications for distribution.

It's literally the manual page for briefcase, and yes, we're gonna read all of it. together. 💅

🦋 SYNOPSIS 🦋

briefcase [command] [platform] [format] [options]

✨ DESCRIPTION ✨

so like, <pink>briefcase</pink> is a tool that lets you convert a Python project into a standalone native application, ready for distribution. no cap.

It supports multiple platforms and formats, which makes it so easy to create, build, and publish applications. it's giving "your side project but make it a real app". 👑

🌸 USAGE 🌸

briefcase [-h] <command> [<platform>] [<format>] [...]

🎀 ENVIRONMENT SETUP 🎀

before you even think about touching Briefcase, you gotta prep your environment, bestie. that means two things: <cyan>Python is installed</cyan>, and you've got a <cyan>virtual environment</cyan> set up. it's a get-ready-with-me but for devs. 🧚

1. Install Python

Briefcase requires Python to be installed on your system. you can use the system's default Python, or manage multiple Python versions using pyenv. pick your fighter. 🥊

Option 1: Use the system Python

most Linux distributions and macOS come with Python pre-installed — lucky you. to check if Python is installed, run:

python3 --version

if Python is not installed, you can install it using your system's package manager. for example:

On Debian/Ubuntu: sudo apt install python3
On macOS (using Homebrew): brew install python

Option 2: Use pyenv to manage Python versions

if you need a specific version of Python, or you're juggling multiple versions (main character energy fr fr), you can use pyenv. to install pyenv, follow the instructions at: https://github.com/pyenv/pyenv

after installing pyenv, you can install a specific Python version, for example:

pyenv install 3.9.7

and set it as the global version:

pyenv global 3.9.7

2. Create a Virtual Environment

it is recommended (read: do it) to use a virtual environment to isolate your project's dependencies. to create and activate a virtual environment, follow these steps:

Create a virtual environment:

python3 -m venv venv

Activate the virtual environment:
- On Linux/macOS: source venv/bin/activate
- On Windows: venv\Scripts\activate

once activated, your terminal prompt will change to indicate that the virtual environment is active. you can now install Briefcase and other dependencies within this environment. slay. ✨

👑 COMMANDS 👑

new — create a new Briefcase project.
dev — run a Briefcase project in the dev environment.
convert — set up an existing project for Briefcase.
create — create a new app for a target platform.
open — open an app in the build tool for the target platform.
build — build an app for a target platform.
update — update the source, dependencies, and resources for an app.
run — run an app.
package — package an app for distribution.
publish — publish an app to a distribution channel.
upgrade — upgrade Briefcase-managed tools.

🌈 PLATFORMS 🌈

android, iOS, linux, macOS, web, windows

💅 OPTIONS 💅

-h, --help — show this help message and exit.
-V, --version — show the program's version number and exit.

🍓 EXAMPLES 🍓

`briefcase new`

the briefcase new command requests basic information to create a new application. the following details are required:

Formal Name: full name of the application (default: "Hello World").
App Name: technical name of the application, without spaces (default: "helloworld").
Bundle: unique app identifier. if you own a domain, enter it in reverse order (e.g., com.example). otherwise, use the default (com.example).
Project Name: name of the project directory (default: "Hello World").
Description: brief description of the application (accept the default or customize).
Author: your name as the author of the project.
Author's Email: your email, used for settings and publishing.
URL: application home page (use your own domain or the default https://example.com/helloworld).
License: choose the project license (default: BSD).
GUI Framework: choose the GUI framework (default: Toga, BeeWare's GUI toolkit).

and here's the lil project tree you get out of it 🎀:

├── venv-venv/
│   └── ...
└── helloworld/
    ├── CHANGELOG
    ├── LICENSE
    ├── pyproject.toml
    ├── README.rst
    ├── src/
    │   └── helloworld/
    │       ├── app.py
    │       ├── __init__.py
    │       ├── __main__.py
    │       └── resources/
    │           └── README
    └── tests/
        ├── helloworld.py
        ├── __init__.py
        └── test_app.py

`briefcase create`

this command installs the dependencies specified in the pyproject.toml file, creating the project structure for the native operating system and configuring the necessary files for packaging and distributing the application:

(venv-venv)$ briefcase create
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10
        [helloworld] Generating application template...
        Using app template: https://github.com/beeware/briefcase-linux-AppImage-template.git, branch v0.3.18
        ...

briefcase create android — this command configures the project structure for packaging on the Android system.

`briefcase build`

this command compiles and prepares a Briefcase project for distribution on the specified platform. it generates the binaries, packages and configurations required to run the application:

(venv-venv)$ briefcase build
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10
        [helloworld] Building application...
        Build bootstrap binary...
        make: Entering directory '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
        ...
        make: Leaving directory '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
        Building bootstrap binary... done
        Installing license... done
        Installing changelog... done
        Installing man page... done
        Updating file permissions... done
        Stripping binary... done

`briefcase run`

this command executes the generated application within the environment prepared by Briefcase, ensuring that all dependencies and configurations are correctly applied:

(venv-venv)$ briefcase run
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10

        [helloworld] Starting app...
        ===========================================================================
        Install path: /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr
        Pre-initializing Python runtime...
        PYTHONPATH:
        /usr/lib/python3.10
        /usr/lib/python3.10/lib-dynload
        /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/lib/helloworld/app
        /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/lib/helloworld/app_packages
        Configure argc/argv...
        Initializing Python runtime...
        Running app module: helloworld

`briefcase package`

this command generates the final files needed to distribute the application, such as target platform-specific installers and packages:

(venv-venv)$ briefcase packahe
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10
        [helloworld] Building .deb package...
        Write Debian package control file... done
        dpkg-deb: building package 'helloworld' in 'helloworld-0.0.1.deb'.
        Building Debian package... done
        [helloworld] Packaged dist/helloworld_0.0.1-1~ubuntu-jammy_amd64.deb

(yes, the example really does say briefcase packahe — we're preserving it exactly as written, typos are part of the historical record 💀🙈)

🔥 SEE ALSO 🔥

check the official documentation at https://briefcase.readthedocs.io/ for more details.

💜 AUTHOR 💜

Briefcase Project — https://github.com/beeware/briefcase/ or https://briefcase.readthedocs.io/en/stable/

Josenilson Ferreira da Silva <nilsonfsilva@hotmail.com> authored this manual. 🫶

and that's the whole page, bestie! this one's BRIEFCASE 1.0.0, dated JAN 2024, and it came to you under the header/footer name BR...E(1) — anyway ily, go build something iconic 💖✨

📦 where this page comes from

debian trixie: python3-briefcase 0.3.22-2 · BSD-3-Clause
ubuntu questing: python3-briefcase 0.3.22-2
ubuntu resolute: python3-briefcase 0.3.25-2 · BSD-3-Clause
ubuntu stonking: python3-briefcase 0.4.1-2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms