Distribute a pywebview app on Windows

Scope

This recipe covers the reproduced Windows 11 x64 route for Python applications that use pywebview with the PySide6 Qt backend. It does not cover browser hosting, every pywebview backend, --onefile, or a standalone native PySide6 application.

The estate maps --onedir to PolyForm Noncommercial/Internal Use distributions because bundled LGPL Qt and other LGPL libraries must remain replaceable by end users. That is not evidence that --onedir is generally better.

Answer

When this LGPL replaceability requirement applies, build a complete PyInstaller --onedir folder with the Qt backend selected, then ship that whole folder as a portable ZIP and as the input to the shared installer. The applications in the evidence estate notify users about GitHub releases. They do not self-update or replace installed files.

Adaptable Windows build command

Use this as a shape to adapt to your own entry script and assets. Keep the full output folder together after the build.

set QT_API=pyside6
pyinstaller --onedir --windowed --name "Your App" ^
  --icon "your_app.ico" ^
  --hidden-import truststore ^
  --add-data "your_ui.html;." ^
  --add-data "your_icon.png;." ^
  --add-data "fonts;fonts" ^
  --collect-all PySide6 ^
  --collect-all qtpy ^
  your_app.py

Replace the icon, UI, font, and entry-script placeholders with the resources your application actually needs. Test the frozen folder, not only a source run.

Decision path

1. Confirm that the intended pywebview backend is Qt with PySide6.
2. Keep PyQt6 out of the build environment when the intended binding is PySide6.
3. Add your real UI assets and runtime data with --add-data or equivalent packaging rules.
4. Collect PySide6, qtpy, and truststore when following this reproduced build shape.
5. Preserve the complete --onedir output folder for the portable ZIP and shared installer route when the replaceability requirement applies.
6. Tell users only that the app can notify them about a GitHub release. Do not describe it as self-updating.

Production evidence

Simple UNA Log Viewer’s build script sets QT_API=pyside6, builds with --onedir and --windowed, adds assets, includes truststore, and collects PySide6 and qtpy. Simple Project Manager’s README documents the pywebview Qt-backend application shape and full-folder distribution. The shared release workflow packages, hashes, attests, and gates release artifacts.

Unsupported or external outcomes

• The evidence does not cover every pywebview backend.
• PyInstaller --onefile and standalone native PySide6 are not reproduced for this mapped PolyForm route. This does not say --onefile universally violates LGPL; other license and distribution models need their own analysis and testing.
• Authenticode-signed artifacts, Store or MSIX, and general WinGet acceptance are external outcomes. Store distribution may be viable but is not reproduced here.
• Hashes and provenance do not establish malware safety or SmartScreen reputation.
• This is not legal advice. Layout alone does not fulfill all license obligations; notices, source or offer requirements, and the actual dependency and license versions still matter.

Related drafts

• Release route hub
• Route selector
• PySide6 distribution
• Installer route

Source ledger