Skip to main content

Distribution

PyWee distribution is wheel-first. The normal PyPI wheel is intentionally small: it contains PyWee code plus a locked Chromium download manifest, not the Chromium binary itself.

Users do not install Chromium manually. PyWee downloads the exact locked runtime into its own cache with pywee chromium install or automatically on first pywee run.

Build A Wheel​

python3 -m pip wheel . -w dist

Normal wheel builds do not download Chromium. To build an offline wheel that does embed Chromium, set:

PYWEE_BUNDLE_CHROMIUM=1 python3 -m pip wheel . -w dist

That offline wheel is platform-specific and usually too large for PyPI's default upload limit.

Verify The Wheel​

Install the built wheel into a clean environment and run:

pywee chromium status
pywee chromium install
pywee chromium verify
pywee init smoke-app
pywee run smoke-app

pywee chromium status reports the managed runtime path. Before install it may show chromium: missing; after install it must print the provider, revision, and SHA256 metadata from .pywee-chromium.json.

Size And PyPI Limits​

PyPI's default upload file size limit is 100 MiB. The normal PyWee wheel stays well below that limit because Chromium is downloaded to the PyWee cache after installation.

Offline bundled wheels are still large. The Linux x64 bundled wheel is about 163 MB after release pruning:

  • Chromium runtime is bundled in the wheel;
  • only en-US locale packs are kept because PyWee launches Chromium with --lang=en-US;
  • generated CHROMIUM_CREDITS.html is included beside the executable.

Do not remove the Chromium executable, WebGL/software rendering libraries, or credits file to chase the 100 MiB limit. Use the normal small wheel for PyPI, or request a PyPI file size limit increase if publishing bundled-runtime wheels.

Editable Install Is Not A Distribution Artifact​

python3 -m pip install -e .

Editable installs are for local source development. They use the same managed runtime cache as the normal wheel.

Platform Support​

The current Chromium lock contains runtime artifacts for:

PyWee platformProviderValidation status
linux-x64Playwright Chromium buildTested by unit, integration, and native Chromium smoke jobs.
linux-arm64Playwright Chromium buildArtifact and packaging path prepared; native execution not tested yet.
windows-x64Playwright Chromium buildPrepared, but not tested yet.
macos-x64Playwright Chromium buildLocked artifact only; not tested.
macos-arm64Playwright Chromium buildLocked artifact only; not tested.

PyWee uses Playwright Chromium artifacts because the executable can generate complete Chromium credits data. The official Chromium snapshot artifacts tested for Linux x64 only exposed a placeholder credits page, which is not acceptable for release packaging. A locked URL and SHA256 means that the artifact is prepared; it does not mean that native execution has been tested.

The current browser identity is Playwright 1.54.0, provider revision 1181, Chromium 139.0.7258.5, and Chromium source tree 8577a6fc1b9f42c36df6d91026d9027bff12cf1a.

Manual CI artifact-audit jobs download Linux ARM64 and Windows x64 archives, verify their SHA256, extract them, and require the expected executable layout. These checks prepare cross-platform release inputs but do not replace a native runtime smoke test.

A platform is not distribution-ready until all of these are true:

  • build_support/chromium.lock.json contains a URL and SHA256 for the platform;
  • offline wheel build downloads and embeds that platform runtime;
  • pywee chromium status reports the managed runtime after installation;
  • a generated app from pywee init opens through the installed wheel;
  • third-party notices for the shipped runtime are included;
  • CHROMIUM_CREDITS.html is generated from the managed runtime and stored beside the Chromium executable in the cache or bundled runtime directory;
  • pywee chromium verify passes on the native target platform;
  • the wheel file size is accepted by the target package index.

License Evidence​

Project license files are copied from LICENSE and NOTICE. Canonical static browser-provider licenses are packaged from pywee/third_party_licenses/ and copied into the LICENSES/ directory of every cached or bundled browser.

Chromium runtime directories include .pywee-chromium.json, which records the exact artifact source URL, revision, provider, platform, and SHA256. They also include CHROMIUM_CREDITS.html, generated from the same runtime with Chromium's --credits switch. pywee chromium verify checks all of these files without requiring network access.

The documentation site separately publishes its production npm notices at /licenses/THIRD_PARTY_LICENSES.txt. Its CI regenerates the dependency graph and fails when the committed evidence is stale or contains an unknown or review-required license.