Briefcase

Bugfixes

* Some error messages that are an expected part of the macOS notarization process are now hidden from default verbosity. (2149)
* Briefcase no longer uses the `--no-python-version-warning` option when invoking pip. This option has been deprecated, is currently a no-op, and will be removed soon. (2149)

Backward Incompatible Changes

* Java JDK 17.0.14+7 is now used to package Android apps. Use ``briefcase upgrade java`` to update your Briefcase-installed JDK instance to this version. (2133)

Misc

* 2136, 2137, 2138, 2141, 2142, 2143, 2144, 2145

Features

* Briefcase will now surface git's error messages if an error occurs when cloning a template repository. (1118)
* Briefcase now supports per-app configuration of `pip install` command line arguments using `requirement_installer_args`. (1270)
* If macOS app notarization is interrupted, the notarization attempt can now be resumed. (1472)
* When a macOS notarization attempt fails, Briefcase now displays the cause of the notarization failure. (1472)
* When an existing project uses the `convert` wizard to add a Briefcase configuration, the updated `pyproject.toml` now includes a stub configuration for all platforms. (1899)
* The `briefcase convert` command can now be used to configure a console-based applications. (1900)
* If Briefcase receives an error invoking a system tool, it will now surface the raw error message to the user in addition to logging the error. (1907)
* The project wizard now generates a more complete configuration file when no GUI framework is selected. (2006)
* The web template now targets PyScript version 2024.11.1. In addition, the web template can provide a base `pyscript.toml` that Briefcase will update as required during the build process. (2080)
* Briefcase now uses native pip handling for iOS installs. (2101)
* When a verbosity level of 3 (i.e., `-vvv`) is selected, any tasks that would normally be performed in parallel will now be performed serially. (2110)
* Linux on arm64 is now a fully supported platform. (2113)
* Project bootstraps now have access to the Briefcase console and the overrides specified with `-Q` options at the command line. (2114)
* Project bootstraps can now define a `post_generate()` extension point. This will be invoked after the new project template has been generated, providing a way for bootstraps to add additional files to the generated project. (2119)

Bugfixes

* Briefcase now uses `ditto` to archive apps for submission to the notarization service, rather than standard `zip` tooling. This ensures that UTF-8 encoding and file system resources are preserved. (1218)
* The Gradle file generated for Android projects now correctly escapes single quotes. (1876)
* Pre-release Python interpreter versions are no longer rejected as matching candidates in PEP 621 `requires-python` checks. (2034)
* Briefcase no longer fails to create projects or builds because it cannot update the Git configuration for the relevant template. (2077)
* Support packages for Linux Flatpak and AppImage builds are now downloaded from the `astral-sh` repository, rather than the `indygreg` repository. This reflect the recent transfer of ownership of the project. (2087)
* A Debian-based system that does *not* have `build-essential` installed, but *does* have the constituent packages of `build-essential` installed, can now build Briefcase system packages. (2096)
* The arguments passed to `xcodebuild` when compiling an iOS app have been modified to avoid a warning about an ignored argument. (2102)
* The hints displayed to the user when an identity has been selected now more accurately reflect the context in which they have been invoked. (2110)

Backward Incompatible Changes

* Flatpak apps no longer request D-Bus session access by default. Most apps have no need to access the D-Bus session, unless they're a development tool that is inspecting D-Bus messages at runtime. If you experience errors related to this change, it is likely caused by an inconsistency between the `bundle` definition in your app configuration, and the way the app describes its bundle ID at runtime. If you *do* require D-Bus access, adding `finish_arg."socket=session-bus" = true` to the Flatpak configuration for your app will restore D-Bus session access. (2074)
* Briefcase can no longer install pure Python iOS packages from a source archive (i.e., a `.tar.gz` file published on PyPI). If a package is pure Python, it *must* be provided as a `py3-none-any` wheel. Briefcase's [iOS platform documentation](https://briefcase.readthedocs.io/en/latest/reference/platforms/iOS/xcode.html#requirements-cannot-be-provided-as-source-tarballs) contains details on how to provide a `py3-none-any` wheel when PyPI does not provide one. (2101)
* The API for project bootstraps has been slightly modified. The constructor for a bootstrap must now accept a console argument; the `extra_context()` method must now accept a `project_overrides` argument. (2114)

Misc

* 2032, 2039, 2043, 2044, 2048, 2049, 2050, 2051, 2052, 2056, 2061, 2062, 2065, 2066, 2072, 2079, 2091, 2092, 2093, 2095, 2100, 2106, 2107, 2108, 2115, 2124, 2126

Features

* Support for Python 3.13 has been added.
* When the available version of Git is older than v2.17.0, an error message now prompts the user to upgrade their install of Git to proceed. (1915)
* Apps packaged for Flatpak and AppImage now use a stripped (and smaller) Python support package. (1929)
* macOS app templates can now specify what part of the support package should be copied into the final application bundle. (1933)
* The Flatpak runtimes for new projects were updated. `org.freedesktop.Platform` will now default to 24.08; `org.gnome.Platform` will now default to 46; and `org.kde.Platform` will now default to 6.7. (1987)
* Briefcase will now validate that the running Python interpreter meets requirements specified by the PEP 621 `requires-python` setting. If `requires-python` is not set, there is no change in behavior. Briefcase will also validate that `requires-python` is a valid version specifier as laid out by PEP 621's requirements. (2016)


Bugfixes

* Document type declarations are now fully validated. (1846)
* The order in which nested frameworks and apps are signed on macOS has been corrected. (1891)
* The spacing after the New Project wizard prompts are now consistent. (1896)
* The documentation link provided when an app doesn't specify Gradle dependencies in its configuration has been corrected. (1905)
* The log filter for iOS has been modified to capture logs generated when using PEP 730-style binary modules. (1933)
* Briefcase is now able to remove symbolic links to directories as part of the template cleanup. (1933)
* If a macOS support package contains symbolic links, those symbolic links will be preserved when the support package is copied into the app bundle. (1933)
* Briefcase will no longer attempt to sign symbolic links in macOS apps. (1933)
* Packages that include `.dist-info` content in vendored dependencies are now ignored as part of the binary widening process on macOS. If a binary package has vendored sub-packages, it is assumed that the top-level package includes the vendored packages' files in its wheel manifest. (1970)
* The types used by `AppContext` in GUI toolkit bootstraps for creating new projects have been corrected. (1988)
* The `--test` flag now works for console apps for macOS. (1992)
* Python 3.12.7 introduced an incompatibility with the handling of `-C`, `-d` and other flags that accept values. This incompatibility has been corrected. (2026)


Backward Incompatible Changes

* Java JDK 17.0.12+7 is now used to package Android apps. Use `briefcase upgrade java` to update your Briefcase-installed JDK instance to this version. (1920)
* Support for Python 3.8 has been dropped. (1934)
* macOS and iOS templates have both had an epoch increase. macOS and iOS projects created with previous versions of Briefcase will need to be re-generated. (1934)
* Any project using binary modules on iOS will need to be recompiled to use the binary linking format and wheel tag specified by `PEP 730 <https://peps.python.org/pep-0730/>`__ (#1934)

Documentation

* A how-to guide for building apps in GitHub Actions CI was added. (400)
* Fixed error in example in briefcase run documentation. (1928)
* Building Briefcase's documentation now requires the use of Python 3.12. (1942)

Misc

* 1877, 1878, 1884, 1885, 1886, 1892, 1901, 1902, 1903, 1904, 1911, 1912, 1913, 1923, 1924, 1925, 1926, 1931, 1932, 1936, 1937, 1938, 1939, 1940, 1951, 1952, 1953, 1954, 1955, 1967, 1971, 1977, 1978, 1979, 1983, 1984, 1985, 1989, 1990, 1991, 1994, 1995, 2001, 2002, 2003, 2009, 2012, 2013, 2014, 2015, 2017, 2020, 2021, 2022, 2023, 2024, 2025, 2031

Features

* Briefcase can now package command line apps. (556)
* Templates that use pre-compiled stub binaries can now manage that artefact as an independent resource, rather than needing to include the binary in the template repository. This significantly reduces the size of the macOS and Windows app templates. (933)
* Template repositories are now fetched as blobless partial Git clones, reducing the size of initial downloads. (933)
* macOS now supports the generation of `.pkg` installers as a packaging format. (1184)
* Android SDK Command Line Tools 12.0 is now used to build Android apps. (1778)
* The new project wizard now includes links to known third-party GUI bootstraps. (1807)
* The name of the license file can now be specified using a PEP 621-compliant format for the `license` setting. (1812)
* The default Gradle dependencies for a Toga project no longer includes `SwipeRefreshLayout`. (1845)

Bugfixes

* Validation rules for bundle identifiers have been loosened. App IDs that contain country codes or language reserved words are no longer flagged as invalid. (1212)
* macOS code signing no longer uses the deprecated "deep signing" option. (1221)
* If `run` is executed directly after a `create` when using an `app` template on macOS or Windows, the implied `build` step is now correctly identified. (1729)
* Escaping of quotation marks in TOML templates was corrected. (1746)
* The Docker version on OpenSUSE Tumbleweed is now accepted and no longer triggers a warning message. (1773)
* The formal name of an app is now validated. (1810)
* macOS apps now generate `info.plist` entries for camera, photo library and microphone permissions. (1820)

Backward Incompatible Changes

* Briefcase now uses a private cache of Cookiecutter templates, rather than the shared `~/.cookiecutters` directory. You can reclaim disk space by deleting `~/.cookiecutters/briefcase-*` and `~/.cookiecutter_replay/briefcase-*` (or the entire `~/.cookiecutters` and `~/.cookiecutter_replay` folders if you are not using Cookiecutter for any other purposes). (933)
* The macOS `app` packaging format has been renamed `zip` for consistency with Windows, and to reflect the format of the output artefact. (1781)
* The format for the `license` field has been converted to PEP 621 format. Existing projects that specify `license` as a string should update their configurations to point at the generated license file using `license.file = "LICENSE"`. (1812)
* The PursuedPyBear bootstrap has been migrated to be part of the PursuedPyBear project. (1834)

Documentation

* Documentation describing manual signing requirement for Android packages has been added. (1703)
* Documentation of Briefcase's support for document types has been improved. (1771)
* Documentation on Briefcase's plug-in interfaces was added. (1807)
* Documentation on the use of passwords in Android publication now encourages users to set non-default passwords. (1816)

Misc

* 1184, 1472, 1777, 1784, 1786, 1789, 1790, 1791, 1792, 1793, 1798, 1799, 1800, 1817, 1819, 1821, 1823, 1839, 1840, 1841, 1842, 1843, 1847, 1850, 1851, 1853, 1857, 1860, 1863, 1867, 1869, 1871, 1872, 1873, 1874

Features

* Existing projects with a `pyproject.toml` configuration can now be converted into Briefcase apps using the `briefcase convert` command. (1202)
* Apps packaged as AppImages are no longer dependent on `libcrypt.so.1`. (1383)
* The `briefcase run` command now supports the `--target` option to run Linux apps from within Docker for other distributions. (1603)
* The hints and recommendations that Docker prints in the console are now silenced. (1635)
* In non-interactive environments, such as CI, a message is now printed to signify a task has begun where an animated bar would be displayed in interactive console sessions. (1649)
* Additional options can now be passed to the `docker build` command for building native Linux packages and AppImages via the `--Xdocker-build` argument. (1661)
* The contents of `pyproject.toml` is now included in the log file. (1674)
* When an app runs on an Android device or emulator, the logging output is now colored. (1676)
* When deep debug is activated via `-vv`, `pip` now installs requirements for the app with verbose logging. (1708)
* The listing of filenames for updating permissions for building native Linux packages is now only shown when verbose logging is enabled via `-v`. (1720)
* When a platform supports a splash screen, that splash screen will be generated automatically based on the app icon, rather than requiring additional configuration. (1737)
* New projects for Toga on GTK3 now recommend using `gir1.2-webkit2-4.1` instead of `gir1.2-webkit2-4.0` for `WebView` support. (1748)

Bugfixes

* When Briefcase can't find `rpmbuild` on an RPM-based system, the message giving install instructions now uses the correct package name. (1638)
* Creating new projects is now compatible with cookiecutter v2.6.0. (1663)
* The minimum version of pip was bumped to 23.1.2 to ensure compatibility with Python 3.12. (1681)
* On Windows, the Android emulator will always open without needing to press CTRL-C. (1687)
* A spurious Android emulator named `INFO` will no longer be included in the list of available emulators. (1697)
* The configuration generated for iOS apps declaring geolocation permissions has been corrected. (1713)
* When using `-r/--update-requirements` for building for Android, the app's requirements are always reinstalled now. (1721)
* When creating a new project, the validation for App Name now rejects all non-ASCII values. (1762)
* Packages created for OpenSUSE now depend on `libcanberra-gtk3-module` instead of `libcanberra-gtk3-0`. (1774)


Backward Incompatible Changes

* WiX v3.14.1 is now used to package Windows apps. Run `briefcase upgrade wix` to start using this version. (1707)
* Java JDK 17.0.11+9 is now used to package Android apps. Use `briefcase upgrade java` to update your Briefcase-installed JDK instance to this version. (1736)
* The `splash` configuration option will no longer be honored. Splash screens are now generated based on the icon image. (1737)
* iOS apps now require 640px, 1280px and 1920px icon image. (1737)
* Android apps now require an `adaptive` variant for icons. This requires 108px, 162px, 216px, 324px and 432px images with a transparent background. The Android `square` icon variant requires additional 320px, 480px, 640px, 960px and 1280px images. (1737)

Documentation

* The documentation contribution guide was updated to use a more authoritative reStructuredText reference. (1695)
* The README badges were updated to display correctly on GitHub. (1763)

Misc

* 1428, 1495, 1637, 1639, 1642, 1643, 1644, 1645, 1646, 1652, 1653, 1656, 1657, 1658, 1659, 1660, 1666, 1671, 1672, 1679, 1683, 1684, 1686, 1689, 1690, 1691, 1692, 1694, 1699, 1700, 1701, 1702, 1710, 1711, 1712, 1716, 1717, 1722, 1723, 1725, 1730, 1731, 1732, 1741, 1742, 1743, 1744, 1745, 1752, 1753, 1754, 1756, 1757, 1758, 1759, 1760, 1761, 1766, 1769, 1775, 1776

Features

* Android apps are now able to customize the libraries included in the app at build time. (485)
* App permissions can now be declared as part of an app's configuration. (547)
* The `-C`/`--config` option can now be used to override app settings from the command line. (1115)
* The verbosity flag, `-v`, was expanded to support three levels of logging verbosity. (1501)
* Briefcase now supports GUI bootstrap plugins to customize how new projects are created. (1524)
* GitPython's debug logging is now included in deep debug output. (1529)
* RCEdit v2.0.0 is now used to build Windows apps. Run `briefcase upgrade` to use this latest version. (1543)
* The Flatpak runtimes for new projects were updated. `org.freedesktop.Platform` will now default to 23.08; `org.gnome.Platform` will now default to 45; and `org.kde.Platform` will now default to 6.6. (1545)
* When creating new projects with the `briefcase new` command, project configuration overrides can be specified via the `-Q` command line argument. For instance, a specific license can be specified with `-Q "license=MIT license"`. (1552)
* New virtual devices for the Android emulator are created using the Pixel 7 Pro skin. (1554)
* The web server for running static web projects now falls back to a system allocated port if the requested port is already in use. (1561)
* Flatpaks are now created with permissions to access the GPU and sound devices. (1563)
* AppImages can now be built for the ARM architecture. (1564)
* Apps can now specify a primary color (for both light and dark modes), and an accent color. If the platform allows apps to customize color use, these colors will be used to style the app's presentation. (1566)
* The version of PursuedPyBear for new projects was bumped from 1.1 to 3.2.0. (1592)
* Python 3.12 is now supported on Android. (1596)
* Android apps can now specify the base theme used to style the application. (1610)
* The Java JDK was upgraded from 17.0.8.1+1 to 17.0.10+7. Run `briefcase upgrade java` to upgrade existing Briefcase installations. (1611)
* When the Android emulator fails to start up properly, users are now presented with additional resources to help resolve any issues. (1630)

Bugfixes

* When a custom Briefcase template from a git repository is used to create an app, Briefcase now ensures that git repository is always used. (1158)
* The filter for iOS build warnings was improved to catch messages from Xcode 15.0.1. (1507)
* When merging dependencies on macOS, file permissions are now preserved. (1510)
* `flatpak-builder` 1.3+ can now be correctly identified. (1513)
* The BeeWare icon of Brutus is now used as the runtime icon for new projects created with PyGame. (1532)
* Linux System RPM packaging for openSUSE Tumbleweed no longer errors with `FileNotFoundError`. (1595)
* Any ANSI escape sequences or console control codes are now stripped in all output captured in the Briefcase log file. (1604)
* The detection of physical Android devices on macOS was made more resilient. (1627)

Backward Incompatible Changes

* The use of AppImage as an output format now generates a warning. (1500)
* Support for creating new projects using PySide2 has been removed. Briefcase's release testing will no longer explicitly verify compatibility with PySide2. (1524)
* The Flatpak build process no longer strips binaries included in third-party (e.g. PyPI) packages that are bundled with the app. (1540)
* New projects will now use `manylinux_2_28` instead of `manylinux2014` to create AppImages in Docker. (1564)
* It is highly recommended that Android applications add a definition for `build_gradle_dependencies` to their app configuration. A default value will be used if this option is not explicitly provided. Refer to [the Android documentation](https://briefcase.readthedocs.io/en/latest/reference/platforms/android/gradle.html#build-gradle-dependencies) for the default value that will be used. (1610)

Documentation

* The common options available to every command have now been documented. (1517)

Misc

* 1504, 1505, 1506, 1515, 1516, 1518, 1519, 1526, 1527, 1533, 1534, 1535, 1536, 1538, 1541, 1548, 1549, 1550, 1551, 1555, 1556, 1557, 1560, 1562, 1567, 1568, 1569, 1571, 1575, 1576, 1579, 1582, 1585, 1586, 1589, 1590, 1597, 1606, 1607, 1613, 1614, 1615, 1618, 1621, 1622, 1623, 1624, 1628, 1632, 1633