Native System Packages

Host Platform Support (Platform support)













All modern Linux distributions have a native format for distributing packages that are integrated into their overall operating system:

  • .deb, used by Debian, Ubuntu, Mint (and others)

  • .rpm, used by Red Hat, Fedora, CentOS, AlmaLinux, openSUSE (and others)

  • .pkg.tar.zst, used by Arch Linux and Manjaro Linux

The Briefcase system backend provides a way to build your app in these system package formats.

Not all Linux distributions are supported!

Briefcase cannot reliably identify every Linux vendor. If your Linux distribution isn’t being identified (or isn’t being identified correctly), please open a ticket with the contents of your /etc/os-release file.

The packaged app includes a stub binary, so that the app will appear in process lists using your app’s name. It also includes a FreeDesktop registration so the app will appear in system menus.

When installed from a Briefcase-produced system package, the app will use the system Python install, and the standard library provided by the system. However, the app will be isolated from any packages that have been installed at a system level.

As the app uses the system Python, system packages are highly dependent on the distribution version. It is therefore necessary to build a different system package for every distribution you want to target. To help simplify this process, Briefcase uses Docker to provide build environments. Using these Docker environments, it is possible to build a system package for any target distribution and version, regardless of the host distribution and version - that is, you can build a Debian Buster package on an Ubuntu 20.04 machine, or an Ubuntu 22.04 package on a RHEL8 machine.

The usage of the system Python also means that system packages are different from most other Briefcase-packaged apps. On other target platforms (macOS and Windows apps, Linux AppImage, etc), the version of Python used to run Briefcase will be the version of Python used by the bundled app. However, when building a system package, Briefcase will use the operating system’s Python3 installation for system packages, regardless of the host Python version. This means you will need to perform additional platform testing to ensure that your app is compatible with that version of Python.

Icon format

Deb packages uses .png format icons. An application must provide icons in the following sizes:

  • 16px

  • 32px

  • 64px

  • 128px

  • 256px

  • 512px

Linux System packages do not support splash screens or installer images.

Additional files

The Linux system app template includes a LICENSE and CHANGELOG file, with stub content. When the application is generated from template, Briefcase will look in the project root folder (i.e., the folder that contains your pyproject.toml) for files with the same name. If these files are found, they will be copied into your project. You should ensure these files are complete and correct before publishing your app.

The Linux system app template also includes an initial draft manfile for your app. This manfile will be populated with the description and long_description of your app. You may wish to add more details on app usage.

Additional options

The following options can be provided at the command line when producing Deb packages:


A Docker base image identifier for the Linux distribution you want to target. The identifier will be in the pattern <vendor>:<codename> (e.g., debian:buster or ubuntu:jammy). You can also use the version number in place of the code name (e.g., debian:10, ubuntu:22.04, or fedora:37). Whichever form you choose, you should be consistent; no normalization of code name and version is performed, so ubuntu:jammy and ubuntu:22.04 will be identified as different versions (even though they the same version).

You can specify any identifier you want, provided the distribution is still supported by the vendor, and system Python is Python 3.8 or later.

The following Linux vendors are known to work as Docker targets:

  • Debian (e.g., debian:bookworm or debian:12)

  • Ubuntu (e.g., ubuntu:jammy or ubuntu:22.04)

  • Fedora (e.g, fedora:39)

  • AlmaLinux (e.g., almalinux:9)

  • Red Hat Enterprise Linux (e.g., redhat/ubi9:9)

  • openSUSE Tumbleweed (e.g., "opensuse/tumbleweed:latest")

  • Arch Linux (e.g., archlinux:latest)

  • Manjaro Linux (e.g., manjarolinux/base:latest)


A configuration argument to be passed to the Docker build command for the app image. For example, to provide an additional build argument to the Dockerfile, specify --Xdocker-build=--build-arg=ARG=value. See the Docker build documentation for details on the full list of options that can be provided.

You may specify multiple --Xdocker-build arguments; each one specifies a single argument to pass to Docker, in the order they are specified.

Application configuration

The following options can be added to the<appname>.linux.system section of your pyproject.toml file; if defined in this section, the values will apply for all Linux distributions for which you build packages.

If you need to override these settings for a specific target vendor, or for a specific distribution version, you can provide increasingly specific sections for vendor and version information. Each distribution is identified by:

  • Vendor base (e.g., debian, rhel, arch, suse)

  • Vendor (e.g, debian, ubuntu, rhel, fedora, opensuse-tumbleweed, arch, manjaro). The vendor identifier may be the same as the vendor base (e.g, in the case of Debian, Red Hat, or Arch)

  • Code name (e.g., a version number, or jammy).

For example, a full configuration for myapp running on Ubuntu 22.04 (jammy) would consist of the following sections:

  • providing global configuration options

  • providing definitions common to all Linux packaging backends

  • providing definitions for all Linux system package targets

  • providing definitions common to all Debian-based packaging targets

  • providing definitions common to all Ubuntu-based packaging targets

  • providing definitions specific to for Ubuntu 22.04 (Jammy).

These configurations will be merged at runtime; any version-specific definitions will override the generic vendor definitions; any vendor definitions will override the vendor-base definitions; and any vendor-base definitions will override generic system package definitions.


A list of operating system packages that must be installed for the system package build to succeed. If a Docker build is requested, this list will be passed to the Docker context when building the container for the app build. These entries should be the format the target Linux distribution will accept. For example, if you’re using a Debian-derived distribution, you might use:

system_requires = ["libgirepository1.0-dev", "libcairo2-dev"]

to make the GTK GI and Cairo operating system development packages available to your app. However, if you’re on a RedHat-derived distribution, you would use:

system_requires = ["gobject-introspection-devel", "python3-cairo-devel"]

If you see errors during briefcase build of the form:

Could not find dependency:

but the app works under briefcase dev, the problem may be an incomplete system_requires definition. The briefcase build process generates a new environment that is completely isolated from your development environment, so if your app has any operating system dependencies, they must be listed in your system_requires definition.

system_requires are the packages required at build time. To specify runtime system requirements, use the system_runtime_requires setting.


A list of system packages that your app requires at runtime. These will be closely related to the system_requires setting, but will likely be different; most notably, you will probably need -dev packages at build time, but non -dev packages at runtime.

system_runtime_requires should be specified as system package requirements; they can optionally include version pins. Briefcase will automatically include the dependencies needed for Python. For example:

system_runtime_requires = ["libgtk-3-0 (>=3.14)", "libwebkit2gtk-4.1-0"]

will specify that your app needs Python 3, a version of libgtk >= 3.14, and any version of libwebkit2gtk.

Any problems with installing or running your system package likely indicate an issue with your system_runtime_requires definition.


When an application is published as a .deb file, Debian requires that you specify a “section”, describing a classification of the application area. The template will provide a default section of utils; if you want to override that default, you can specify a value for system_section. For details on the allowed values for system_section, refer to the Debian Policy Manual.


Any additional Docker instructions that are required to configure the container used to build your Python app. For example, any dependencies that cannot be configured with apt-get could be installed. dockerfile_extra_content is string literal that will be added verbatim to the end of the project Dockerfile.

Any Dockerfile instructions added by dockerfile_extra_content will be executed as the brutus user, rather than the root user. If you need to perform container setup operations as root, switch the container’s user to root, perform whatever operations are required, then switch back to the brutus user - e.g.:

dockerfile_extra_content = """
RUN <first command run as brutus>

USER root
RUN <second command run as root>

USER brutus