0.4.4

Bugfixes

• The Toga bootstrap now enforces a dependency on libgirepository 2.0. This is required by changes introduced in Toga 0.5.5. (#2919)

Backward Incompatible Changes

• The Toga app generated by Briefcase is no longer compatible with Debian 12 or Ubuntu 22.04. (#2919)

Misc

• #2920, #2921, #2922, #2923, #2924, #2925, #2926

0.4.3

Features

• Linux system packages can now define a custom man page by setting man_page in pyproject.toml. (#2545)
• macOS PKG installers can now include additional installer resources, configured with the installer_resources setting. (#2561)
• MSI post-install and pre-uninstall scripts can now identify if they are running unattended. (#2781)
• MSI installers now provide the user the ability to check disk space requirements prior to install. (#2783)
• Windows MSIs with a post-install or pre-uninstall script will no longer display a console window when running in quiet mode. Script output will be captured by the installer log. (#2789)
• The minimum supported Windows build number can now be specified using the min_os_version option. (#2855)
• When a selection prompt provides a single option, it is now automatically selected as the default. (#2856)
• MSI installers will now check that the app is not running or has open files before uninstalling. (#2862)
• macOS PKG installers can now run a post-install script, configured with the post_install_script setting. (#2865)
• macOS notarization state is now persisted automatically during briefcase package. If notarization is interrupted, rerunning the same package command will detect the interrupted notarization and resume it without requiring the --resume flag. (#2883)
• The macOS notarization auto-resume workflow now allows for resuming notarization with only the distribution artefact - usually the contents of the dist directory. (#2887)
• The macOS package command now accepts a --no-wait option that will submit an app for notarization without waiting for the notarization to complete. The submission can be finalized later by re-running briefcase package. (#2888)

Bugfixes

• Briefcase now rejects project paths that contain commas or invisible left-to-right marks before project generation starts. (#2580)
• Bundle identifiers with 2 parts are no longer rejected by the validation process. (#2824)
• Briefcase now warns when an app's description is longer than 80 characters, as overly long descriptions can be truncated by some packaging formats (such as Windows MSI shortcut icons). (#2864)
• Briefcase is now able to display application logs when running apps under macOS 26. If you are experiencing this problem, you will also need to either (a) upgrade std-nslog to 2.0.0+, or target your application at Python 3.14 (or newer). (#2877)
• If a Linux Flatpak project specifies the use of a base image, Briefcase now verifies that base is installed and available. (#2905)

Documentation

• The Windows code signing guide now describes how to generate a self-signed certificate for testing. (#2899)

Misc

• #2127, #2559, #2820, #2821, #2822, #2823, #2826, #2827, #2829, #2830, #2837, #2845, #2849, #2850, #2851, #2852, #2854, #2857, #2858, #2859, #2860, #2866, #2872, #2874, #2875, #2876, #2879, #2880, #2881, #2882, #2885, #2892, #2893, #2894, #2895, #2896, #2897, #2898, #2902, #2904, #2906, #2907, #2908, #2909, #2910, #2911, #2912, #2913, #2916

0.4.2

Features

• Dynamic PEP 621 metadata in pyproject.toml will now be resolved by invoking the PEP 517 [build-system] interface. (#474)
• Briefcase can now build Windows apps and installers for ARM64 devices. (#1887)
• License metadata in pyproject.toml is now parsed and validated using PEP 639 format (i.e., license = "<SPDX expression>" and license-files = [...]). (#2146)
• The new project wizard now provides more detailed information about community bootstraps that are available. (#2342)
• Error messages for macOS and iOS wheel compatibility now include the Python version. (#2658)
• Android apps can now specify the ABIs that they target. (#2723)
• The Briefcase repository now has an AGENTS.md file and Spec Kit constitution to provide assistance for Generative AI tools. (#2733)
• MIME type definitions on document types are now validated as part of the validation of a configuration. (#2738)
• Windows MSI installers can now customize the background image used on the first page of the installer, and the banner image used on all subsequent pages of the installer. (#2782)
• It is now possible to create a "skinless" Android emulator by specifying a device type, but no skin, as part of a device specification. (#2788)
• Windows MSI installers can now verify the availability of .NET runtimes as a pre-condition for installation. (#2804)
• When an app fails to run or returns an error, the status code is now reported in the console. (#2806)

Bugfixes

• (CVE-2026-33430) When a Windows MSI is installed for All Users, the installation folder no longer inherits the permissions of the parent folder. The fix for this issue has been backported to the templates for Briefcase v0.4.1, v0.4.0 and v0.3.26. (#2759)
• Briefcase has been made more resilient to permission errors when renaming recently created directories on Windows. (#1780)
• Android system image verification now uses sdkmanager --list_installed to confirm the image is fully installed, rather than only checking if the directory exists. If the image is not installed, it will be downloaded automatically. (#1895)
• MSI pre/post install scripts now run with elevated privileges when installed for "All Users". (#2722)
• Briefcase will now prevent the user from using an x86_64 Python interpreter on an Apple Silicon machine. (#2736)
• On macOS, any wheel that doesn't contain a tag ending -any will now be identified as binary content that requires a merge. Previously, the Root-Is-Purelib wheel metadata was used to determine if a package was "pure"; this flag has proven to be unreliable under some circumstances. (#2753)
• Version number validation has been improved. Dynamic version number specifications (e.g., {attr: ...}) that have been historically permitted by tools like setuptools are now rejected with a more helpful error message. (#2765)

Backward Incompatible Changes

• Apps now require a valid PEP 639 license configuration. Apps in legacy formats — PEP 621 license.file, license.text, and bare free-text strings — are automatically coerced to PEP 639 format on a best-effort basis, with warnings raised about any automated conversion that has occurred. Apps with no license definition can still be built, but a placeholder license file and a LicenseRef-UnknownLicense license expression will be used. (#2146)
• New PySide6 apps now default PySide 6.10. This adds support for Python 3.14, but also enforces a minimum supported macOS version of 13.0 (Ventura). (#2658)

Misc

• #2563, #2734, #2739, #2741, #2742, #2743, #2744, #2746, #2747, #2748, #2749, #2750, #2756, #2757, #2761, #2762, #2763, #2764, #2766, #2770, #2771, #2773, #2775, #2776, #2777, #2778, #2779, #2784, #2785, #2786, #2787, #2790, #2791, #2792, #2793, #2794, #2795, #2800, #2801, #2802, #2807, #2812, #2813, #2814, #2816, #2819

0.4.1

This release adds no new features; it is purely to overcome a problem with a transitive dependency on binaryornot that prevents basic Briefcase usage of templates.

Bugfixes

• Briefcase now imposes a version pin on binaryornot < 0.5.0. Recent binaryornot releases introduced a series of bugs that cause catastrophic errors in PNG detection and file encoding. (#2712)

Misc

• #2726, #2727, #2729, #2730

0.4.0

Features

• When running briefcase dev on Linux, system requirements are now checked before attempting to install Python requirements. (#1137)
• Development mode now runs apps in an isolated virtual environment, rather than the environment running Briefcase. (#1735)
• Android apps can now be built and run in debug mode. (#2351)
• CachyOS is now detected as an "Arch-like" Linux distribution when creating a system package. (#2591)
• If content in sources and test_sources has duplicated structure, Briefcase will now merge those structures rather than raise an error. (#2636)
• Post-install scripts for MSI installers now expose an INSTALLER_PATH environment variable. (#2637)
• The open command now accepts a -a/--app option to allow opening a single app in a multi-app project. (#2651)
• Android apps can now revoke permissions before startup via --revoke-permission. (#2664)
• Publication channels are now discovered via entry points, allowing third-party plugins to provide custom briefcase publish channels. (#2687)

Bugfixes

• Briefcase now accepts PEP 440 requires-python version ranges (e.g., >=3.14,<4.0). (#2604)
• When using -a/--app, Briefcase now only finalizes the selected app instead of finalizing all apps in the project. (#2654)
• macOS wheels that are tagged with both universal2 and individual architecture tags are now correctly processed as part of the architecture merging process. (#2690)
• Briefcase now accepts more version numbers as valid, including leading zeros in version components (e.g., 25.09.2), and accepting all forms of capitalization in number suffixes (e.g., accepting both 1.2RC3 and 1.2rc3). (#2693)
• Debian packages can now be built for projects that contain an underscore in the app name. Previously, this would raise an error as underscores are not allowed in Debian package names. The Debian package name will be based on the bundle name - that is, the app name, but with underscores replaced with hyphens. (#2699)
• Linux projects can now install extras on requirements that are specified as a reference to a local source directory. (#2700)

Backward Incompatible Changes

• Runtime requirements for Debian apps using PySide6 have been simplified. If you have an existing project, it may be possible to simplify your runtime requirements to only include libgl1, libqt6dbus6, libqt6gui6, and libxcb-cursor0. To support Ubuntu 22.04, you will also need to include libxcb-icccm4, libxcb-keysyms1, libxcb-shape0 and libxkbcommon-x11-0. (#2592)
• Bundle names and identifiers are now normalized to lower case. Bundle identifiers are derived from domain names, so they should always be lower case; Briefcase now enforces this. If you have historically used upper case letters in your bundle identifier or app name, your bundle name will change as a result of this update. (#2699)

Documentation

• The documentation now contains a comprehensive contribution guide. (#2605)

Misc

• #2525, #2596, #2597, #2598, #2599, #2600, #2609, #2610, #2611, #2612, #2613, #2615, #2616, #2617, #2618, #2619, #2622, #2623, #2625, #2627, #2629, #2631, #2633, #2641, #2643, #2644, #2645, #2646, #2647, #2648, #2649, #2650, #2652, #2655, #2657, #2660, #2661, #2662, #2663, #2665, #2666, #2670, #2671, #2672, #2673, #2674, #2675, #2676, #2677, #2679, #2681, #2682, #2683, #2684, #2685, #2686, #2687, #2688, #2704, #2705, #2708, #2710, #2713, #2715, #2716, #2717, #2718, #2719

0.3.26

Features

• When a project specifies a dependency using a local file path, briefcase dev now installs that dependency in editable mode. This means changes in the local project will be immediately reflected in the development environment, without needing to reinstall the package. (#2334)
• The build and run commands for Windows, macOS and iOS now have a --debug option for integration with PDB and Visual Studio Code. (#2147, #2352)
• Windows MSI installers can now include post-install and pre-uninstall scripts, including selection of optional features as part of the install and uninstall process. (#2191, #2573)
• Windows MSI installers now display and ask for acceptance of the project's license as part of the install process. (#2191)
• Briefcase's web backend now gives full control of the PyScript and GUI toolkit configuration to the Python packages that are installed in the app. (#2337)
• briefcase dev no longer overwrites explicitly set environment variables. (#2497)
• Briefcase now has a cross-platform representation of Bluetooth permissions. (#2522)
• When packaging an app in MSI format, creation of Start menu shortcuts can now be disabled with the install_launcher setting. (#2534)
• Windows MSI installers now provide the option for users to configure the install directory for apps. (#2553)
• When a project defines multiple applications, briefcase devand briefcase run now display an interactive menu allowing the user to select which application to start. (#2574)
• Briefcase now has the ability to manage virtual environments as part of a development environment. This feature is only used as part of the in-progress dev command for the web environment, but opens up opportunities for better environment isolation in the future. (#2334)

Bugfixes

• The docs checks in tox now work if there are spaces in the path. (#2477)
• The system Python version check now works on Gentoo Linux. (#2490)
• Developer mode is now able to track the need to install requirements on a per-environment basis. (#2495)
• Permission disabling is now handled correctly (#2522)

Backward Incompatible Changes

• Java JDK 17.0.17+10 is now used to package Android apps. Use briefcase upgrade java to update your Briefcase-installed JDK instance to this version. (#2529)

Documentation

• Briefcase's documentation was migrated to Markdown format. (#2502)
• The obligations of a "well behaved" MSI-packaged application in ensuring a clean registry have been documented. (#2554)

Misc

• #2381, #2384, #2457, #2459, #2460, #2461, #2462, #2466, #2467, #2468, #2469, #2470, #2471, #2478, #2479, #2481, #2482, #2484, #2485, #2487, #2492, #2493, #2499, #2500, #2504, #2505, #2506, #2507, #2508, #2509, #2511, #2512, #2517, #2518, #2519, #2520, #2520, #2521, #2523, #2524, #2526, #2528, #2533, #2535, #2536, #2537, #2538, #2539, #2540, #2541, #2542, #2544, #2548, #2549, #2550, #2551, #2552, #2555, #2556, #2557, #2558, #2564, #2565, #2566, #2568, #2568, #2569, #2570, #2571, #2572, #2576, #2577, #2585, #2586, #2589, #2590

0.3.26rc5

Release candidate 5 of Briefcase 0.3.26.

0.3.25

Features

• Android apps can now pass --forward-port and --reverse-port to connect ports in the emulated device to the host environment (#2369)
• Support for Python 3.14 has been added. (#2431)
• Windows apps and Visual Studio projects can now reference pre-release Python versions as a support revision. (#2432)
• If an iOS or macOS app doesn't specify a minimum OS version, the minimum OS version is now derived from the support package, rather than being hard coded. (#2443)
• Android applications now target Android SDK 35 by default. (#2393)

Bugfixes

• Apps that contain file paths longer than 260 characters can now be included in MSI installers. (#948)
• Windows builds now have improved hints when a virus checker interrupts a build. (#1530)
• Wheels that contain Linux .so files are now usable on macOS. (#2429)
• iOS and macOS apps now read the minimum supported OS version from the Python framework's metadata, rather than requiring a VERSIONS file as part of the support package. (#2443)

Backward Incompatible Changes

• Support for Python 3.9 has been dropped. (#2431)

Documentation

• Details on usage of iOS and Android third-party wheels have been updated to reflect recent changes in the Python packaging ecosystem. (#2423)

Misc

• #2334, #1650, #2364, #2378, #2379, #2381, #2389, #2394, #2402, #2406, #2407, #2408, #2411, #2413, #2415, #2416, #2417, #2422, #2425, #2427, #2434, #2436, #2438, #2439, #2440, #2441, #2445, #2446, #2447, #2448, #2449, #2452, #2453, #2454, #2455

0.3.24

Features

• When an iOS or macOS binary wheel cannot be found, the error message now provides more useful hints regarding the possible cause. (#2230)
• Document type and file associations have been improved on macOS. (#2284)
• Briefcase can now be used to sign, package and notarize apps that Briefcase didn't create. You can now use another tool to create a macOS, Windows or Linux application, and then use Briefcase to complete the process of turning that app into a signed and notarized release artefact. (#2326)

Bugfixes

• A redundant signing phase has been removed when packaging an apps for macOS. (#1099)
• An error is now raised on macOS if Briefcase is used on an iCloud mounted drive. iCloud synchronization adds metadata to some folders, which is incompatible with the signing process. (#1808)
• An app's formal name can now include a . character. (#2151)
• Distribution-specific cumulative settings (such as requires) now correctly accumulate, rather than overwriting more general values. (#2188)
• Briefcase will now default to using the system certificate store when performing HTTPS downloads. (#2296)
• Briefcase now provides richer error information when it is unable to complete a download. In particular, issues associated with SSL verification are now reported as such, rather than as a generic "are you offline?" message. (#2296)
• The presence of a PIP_REQUIRE_VIRTUALENV environment marker no longer influences the operation of dependency installation on iOS. The iOS installation environments is inherently isolated, so this flag is redundant; but in some circumstances, it would prevent the installation of dependencies into a project. (#2325)

Backward Incompatible Changes

• Briefcase now uses WiX version 5.0.2 to generate MSI installers on Windows. Any Windows apps created with previous versions of Briefcase will need to be re-generated by running briefcase create. (#1185)

Documentation

• Documentation about deploying to physical iOS devices has been added. (#1190)
• References to Briefcase's settings are now hyperlinked for ease of cross-referencing. (#2341)
• A guide for publishing apps to the macOS App Store has been added. (#2360)
• Briefcase's documentation now uses a header and style consistent with the BeeWare website. (#2375)

Misc

• #1669, #1696, #2280, #2281, #2287, #2288, #2289, #2291, #2292, #2295, #2310, #2311, #2312, #2313, #2319, #2320, #2321, #2322, #2323, #2324, #2327, #2330, #2331, #2335, #2339, #2343, #2343, #2345, #2346, #2347, #2349, #2358, #2359, #2361, #2362, #2367, #2371, #2372, #2373, #2374, #2380, #2385, #2386

0.3.23

Features

• Cookiecutter filters for escaping XML content and attributes have been added. (#2103)
• Briefcase now supports the use of HISTORY, NEWS and RELEASES as filenames for the change log of a project (in addition to CHANGELOG). It also supports the use of .md, .rst and .txt extensions on those files. (#2116)
• It is now possible to ask boolean question using the Console Interface. (#2128)
• The create, build, package and update commands can now be run on a single app within a multi-app project by using the -a / --app option. (#2148)
• The Toga app bootstrap now generates apps that use Toga 0.5. (#2193)
• An app can now enforce a minimum supported OS version by defining a min_os_version configuration item on a per-platform basis. This minimum value will be used on macOS, iOS and Android deployments. (#2233)
• The Flatpak runtimes for new projects were updated. org.gnome.Platform will now default to 47; and org.kde.Platform will now default to 6.9. (#2258)
• Android packages are now built using version 19.0 of Android's Command-line Tools; this version will be automatically installed at first use. (#2260)
• When creating a new project with briefcase new, or converting an existing project with briefcase convert, Briefcase will now try to infer the author's name and email address from the git configuration. (#2269)

Bugfixes

• .pth files created by packages installed as dependencies are now correctly processed during application startup on macOS, Windows, Linux and iOS. (#381)
• Error handling during JDK upgrades has been improved. (#1520)
• The iOS log filter was improved to hide an message about getpwuid_r that can be ignored. (#2163)
• New apps using Toga on Linux will impose an upper version pin on PyGObject, limiting that package to < 3.52.1. This is required to ensure that older Debian-based distributions are supported by default. This pin can be removed if these support for these distributions is not required, as long as some additional changes are made to the system_requires and system_runtime_requires definitions. The required changes are included (commented out) as part of the new project template. (#2190)
• License names now follow the SPDX License List. (#2270)

Backward Incompatible Changes

• Briefcase can no longer install pure Python macOS 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 macOS platform documentation contains details on how to provide a py3-none-any wheel when PyPI does not provide one. (#2163)
• The app_packages folder now occurs after the app folder in the package resolution path on Windows, Linux, macOS and iOS. This will result in subtle changes in behavior if you have packages defined in your sources that have the same name as packages installed from your requires. (#2204)
• The iOS app template no longer uses the iphoneos_deployment_target setting to configure the minimum OS version. This variable was undocumented; you should modify any usage of this variable to the newly added (and documented) min_os_version setting. (#2233)
• If you have a PySide6 app deployed to macOS, you must add min_os_version = "12.0" to your macOS project configuration. As of PySide 6.8.0, PySide6 macOS wheels are tagged with a minimum supported macOS version of 12.0. Previously, Briefcase would install the macOS 12 wheel, but the Briefcase app would declare itself as supporting macOS 11. This would cause errors if the app was run on macOS 11. Briefcase will no longer install macOS wheels that are incompatible with the minimum OS version declared by the app (11.0 by default). The additional min_os_version configuration option is now required to allow Briefcase to resolve the installation of PySide6 wheels. (#2240)
• Java JDK 17.0.15+6 is now used to package Android apps. Use briefcase upgrade java to update your Briefcase-installed JDK instance to this version. (#2259)
• The new command now uses SPDX identifiers when referring to licenses. If you have been using the -Q license=XXX option to automate application creation, you will need to modify the value provided to match the SPDX specifier for that license (e.g., MIT instead of MIT license, and BSD-3-Clause instead of BSD). (#2270)

Documentation

• A how to guide for command-line apps was added. (#1947)
• Platform notes were added on removing static binary content from iOS and macOS apps. (#2161)
• The macOS and Windows platform documentation has been simplified to remove duplication of content between output formats. (#2162)

Misc

• #1696, #2153, #2155, #2158, #2159, #2160, #2168, #2169, #2170, #2171, #2172, #2174, #2175, #2176, #2177, #2178, #2179, #2184, #2185, #2186, #2196, #2205, #2206, #2207, #2208, #2209, #2210, #2215, #2217, #2218, #2219, #2220, #2221, #2222, #2223, #2237, #2247, #2248, #2249, #2262, #2263, #2264, #2265, #2266, #2267, #2276, #2277, #2278