Evaluate BeeWare Briefcase for Anki packaging and distribution

[abdnh]

Context

The migration from PyOxidizer to the UV-based launcher (#3081, #4074) has created significant UX regressions despite solving critical technical problems. Users report that the terminal-based installation process appears "virus-like" and creates confusion, particularly for non-technical users. The offline installer request (#4241) has 29 upvotes, and the GUI launcher request (#4152) has 18 upvotes.

BeeWare Briefcase discussion #2316 contains a proof of concept demonstrating that Briefcase can package Anki. In a meeting with Russell Keith-Magee (Briefcase creator), @dae, and the AnkiHub team, Russell estimated implementation could be completed in as little as one day.

Goal

Determine whether Briefcase can produce production-ready native installers (MSI/DMG/DEB) for all supported Anki platforms while preserving or improving upon current functionality.

Definition of Done

We have validated that Briefcase either can or cannot meet Anki's packaging requirements on all supported platforms by answering these questions:

1. Binary dependency handling
   • Confirm Briefcase correctly installs and bundles rsbridge (PyO3/Rust extension)
   • Verify PyQt6 and all binary dependencies work across Windows/macOS/Linux
   • Test platform-specific wheels
2. Native installer generation
   • Windows: Generate MSI installer (or confirm directory output works with existing NSIS wrapper)
   • macOS: Generate signed and notarized DMG with proper .app bundle
   • Linux: Generate DEB package (DEB preferred over AppImage/Flatpak for compatibility)
3. Startup performance
   • Measure cold start time vs. current launcher
   • Document any performance regression and evaluate mitigations (zip stdlib, PYC precompilation)
4. Process identity
   • Determine if Briefcase-packaged app appears as "Anki" (not "Python") in Task Manager/Dock
   • If not, document an approach to preserve launcher entrypoint while using Briefcase for packaging
5. Offline capability
   • Confirm installer is fully offline-capable (no runtime dependency downloads) - is this what we want/need?
   • Validate total installer size is acceptable
6. Auto-update compatibility
   • Document whether the existing Tools > Upgrade/Downgrade mechanism can be preserved - If not, outline required changes to update architecture
7. Build pipeline integration
   • Confirm Briefcase can be integrated into existing BuildKite CI/CD
   • Document platform-specific build requirements (Briefcase cannot cross-compile)

Non-Goals

Migrating Anki's GUI to Toga

Mobile platform support via Briefcase

Success Criteria

Briefcase is feasible if all seven validation points pass or have documented, acceptable workarounds.

Briefcase is not feasible if any blocker exists that cannot be resolved within a reasonable implementation timeline (e.g., unacceptable startup time regression with no mitigation path).

Related Issues

#3081 - PyOxidizer abandonment

#4074 - UV launcher implementation

#4151 - Python integration in launcher

#4152 - GUI launcher (18 upvotes)

#4241 - Offline installer request (29 upvotes)

#4144 - Process identity (Task Manager/Dock naming)

#4556 - Revisiting the launcher

References

Briefcase discussion with Anki PoC

Briefcase documentation - Packaging external apps

[andrewsanchez]

Scrappy WIP we can use for reference:

Reference implementation: https://github.com/AnkiHubSoftware/anki-briefcase-test/blob/main/helloworld/src/helloworld/app.py
This is a work in progress that I have just started fiddling with

[abdnh]

I'm exploring how we can integrate it into the repo: https://github.com/abdnh/anki/tree/briefcase

I had to generate pyproject.toml from a template to specify version & dependencies because briefcase doesn't support dynamic metadata: beeware/briefcase#474

[abdnh]

I ran into an issue with macOS universal builds:

fatal error: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/lipo: /Users/abdo/dev/anki-briefcase-test/helloworld/build/helloworld/macos/app/app_packages.arm64/orjson/orjson.cpython-313-darwin.so and /Users/abdo/dev/anki-briefcase-test/helloworld/build/helloworld/macos/app/app_packages.x86_64/orjson/orjson.cpython-313-darwin.so have the same architectures (x86_64) and can't be in the same fat output file
   | ━━━━━━━━━━━━━━━━━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━━━ 46.9% • 00:02

Unable to create fat library for orjson/orjson.cpython-313-darwin.so

Looks like a bug in Briefcase.

I tested with universal_build = false and got a working .dmg package.

Briefcase also doesn't seem to recognize calver.

[freakboy3742]

EDIT: Hi - I'm one of the maintainers of BeeWare/Briefcase.

Unable to create fat library for orjson/orjson.cpython-313-darwin.so

I've seen this before, this usually indicates a bug in the upstream package - usually a package that has been incorrectly tagged and published as a universal2 wheel when it's actually a single-platform binary (or vice versa).

In this case, the tagging for orjson is ... odd. It publishes a wheel that is tagged cp313-cp313-macosx_10_15_x86_64.macosx_11_0_arm64.macosx_10_15_universal2.whl - that is, it's tagged as a single platform x86-64 binary and single platform arm64 binary... and a universal2 binary.

I think that's legal, but it's definitely unconventional (this is the first time I've seen all three tags on a single package). I'll dig into this a bit and report back.

Briefcase also doesn't seem to recognize calver.

I'm not sure what you mean by "recognise" calver. It requires a PEP 440 compliant version number, but other than that, Briefcase doesn't do much with version numbers other than substitute them into files where required. Can you elaborate on the problem you're seeing here?

beeware/briefcase#474 is a known (and long standing) feature request though, and is definitely something we'd like to fix.

[abdnh]

Hi @freakboy3742!

I'm not sure what you mean by "recognise" calver. It requires a PEP 440 compliant version number

The package command fails with this:

Briefcase configuration error: Version number (25.09.2) is not valid.

Version numbers must be PEP440 compliant; see https://www.python.org/dev/peps/pep-0440/ for details.

I looked into this more and found that the regex used is outdated. PR submitted: beeware/briefcase#2689

[abdnh]

I did some tests on Ubuntu 24 and ran into a few issues building a .deb package:

1. dpkg-deb fails if the app name has underscores (e.g. "anki_launcher"):

dpkg-deb: error: package name has characters that aren't lowercase alphanums or '-+.'

This is trivial to work around, but I'm reporting it in case something can be improved here.

2. We would actually like the app/executable name to be "anki", but this conflicts with Anki's own package, which is also named "anki". I noticed Briefcase uses formal_name on Windows for GUI apps so no problem there, but it uses the app name on Linux.

3. Extras don't work with local wheel paths on Linux (Briefcase apparently treats the whole string as a literal path). We need to use something like this: "../wheels/aqt.whl[qt,audio]"

Here's the current pyproject.toml file: https://github.com/abdnh/anki/blob/briefcase/qt/installer/pyproject.toml.template

@freakboy3742 Any thoughts?

UPDATE: I think I got it working with anki as the app name by modifying sys.path and sys.modules: abdnh@05228ec#diff-1d808fce6080340a35a9125378245d4cd5d357f3a78891b2562b581e5a681b07

[freakboy3742]

I did some tests on Ubuntu 24 and ran into a few issues building a .deb package:

1. dpkg-deb fails if the app name has underscores (e.g. "anki_launcher"):

dpkg-deb: error: package name has characters that aren't lowercase alphanums or '-+.'

This is trivial to work around, but I'm reporting it in case something can be improved here.

Thanks - I'm guessing you've found the workaround of suing an app name of anki-launcher rather than anki_launcher; the longer term fix is that Briefcase has 3 versions of "code-facing name":

• app_name - what the configuration literally defines
• module_name - the name in "Python module compatible" form - app_name.replace("-","_")
• bundle_name - the name in "bundle compatible" form - app_name.replace("_", "-")

It looks like deb packages (and possibly other linux packages) should be using bundle_name rather than app_name for the package name. I've opened #2699 to track this issue.

2. We would actually like the app/executable name to be "anki", but this conflicts with Anki's own package, which is also named "anki". I noticed Briefcase uses formal_name on Windows for GUI apps so no problem there, but it uses the app name on Linux.

The difference with GUI apps is that the user presentation is an icon, so spaces and capitalisation in the name isn't a problem - you're clicking on an icon. We've historically fallen back to app_name for command-line executables since that's seemed like a reasonable starting point for an executable - but I guess a custom exe_name configuration point (defaulting to app_name if undefined) could make sense.

Another option (and something that I've been considering as part of the larger PEP 621 normalisation effort) is to lean in to entry points as the source of definitions for the binaries that will be executed. That would provide a way for a single console app to define multiple executable entry points. See #2634 for some discussion about this.

3. Extras don't work with local wheel paths on Linux (Briefcase apparently treats the whole string as a literal path). We need to use something like this: "../wheels/aqt.whl[aqt,audio]">

I've had a bit of a poke at this one - I can confirm I can see the same problem, and I understand why it's happening. It's essentially only an issue on Linux, because of the slightly circuitous approach to installing dependencies that is required in order to support building in Docker. I've opened #2700 to track the problem.