Skip to content

Publish web app as static website

Instructions for publishing a Flet app as a standalone static website (SPA) that runs entirely in the browser with Pyodide. No Python code runs on the server.

Pyodide is a port of CPython to WebAssembly (WASM) and has some limitations.

Native Python packages

Native Python packages (vs "pure" Python packages written in Python only) are packages partially written in C, Rust, or other languages producing native code. Example packages are numpy, cryptography, lxml, pydantic-core.

Pyodide comes with a list of built-in packages. To use a package from PyPI, it must be pure Python or provide a wheel built for Emscripten.

Async and threading

Static websites run in a single browser thread. You can use sync and async handlers, but long-running CPU work or blocking calls will freeze the UI. Prefer async I/O, or move heavy work to a server and call it via a web API.

Micropip

Pyodide installs packages with micropip. You can use the Micropip API directly in your Flet app:

import sys

if sys.platform == "emscripten":
    import micropip
    await micropip.install("regex")

There are two ways to publish a static website:

  • flet build web - recommended; uses Flutter and packages dependencies into the output.
  • flet publish - no Flutter required; installs dependencies at runtime with micropip.

flet publish#

flet publish is alternative to flet build web that does not require Flutter. It packages your app and installs dependencies in the browser at runtime via micropip. Initial load time is usually higher than flet build web.

To publish an app, run:

flet publish <path-to-app.py>

The website is published to --distpath (default: ./dist).

Testing the site#

You can try published Flet app using flet serve command:

flet serve dist

Then, open http://localhost:8000 in your browser to check the published app.

Assets#

If the assets directory exists (default: ./assets), its contents are copied to the published site root. Use --assets to point to a different folder. Assets are not packaged inside the app.tar.gz.

flet build web#

Publish a static website using Flutter and Pyodide.

Note

Complementary and more general information is available here.

Testing the site#

flet serve serves the default output directory (./build/web):

flet serve

Configuration options#

These settings apply to flet build web and flet publish, unless noted.

Base URL#

Use a base URL when hosting your app in a subdirectory. Flet normalizes it to /<value>/ and uses / when unset.

Resolution order#

Its value is determined in the following order of precedence:

  1. --base-url
  2. [tool.flet.web].base_url
  3. "/"

Example#

flet build web --base-url /myapp/

[tool.flet.web]
base_url = "/myapp/"

Route URL strategy#

Controls how routes are represented in the URL:

  • path - clean paths; requires SPA-capable hosting.
  • hash - uses the URL hash; works on static hosts without SPA support.

Resolution order#

Its value is determined in the following order of precedence:

  1. --route-url-strategy
  2. [tool.flet.web].route_url_strategy
  3. "path"

Example#

flet build web --route-url-strategy hash

[tool.flet.web]
route_url_strategy = "hash"

Web renderer#

Selects the Flutter web renderer:

  • auto (default) - let Flutter choose the best renderer
  • canvaskit
  • skwasm

Resolution order#

Its value is determined in the following order of precedence:

  1. --web-renderer
  2. [tool.flet.web].renderer
  3. "auto"

Example#

flet build web --web-renderer canvaskit

[tool.flet.web]
renderer = "canvaskit"

CDN assets#

By default, Pyodide, CanvasKit, and fonts are loaded from CDNs to keep the output small. Disable CDN loading for offline or air-gapped deployments.

Resolution order#

CDN loading is disabled in the following order of precedence:

  1. --no-cdn
  2. [tool.flet.web].cdn = false
  3. default: CDN enabled

Example#

flet build web --no-cdn

[tool.flet.web]
cdn = false

PWA colors#

Configure PWA colors used in manifest.json and browser UI.

Resolution order#

For each setting:

  1. --pwa-background-color / --pwa-theme-color
  2. [tool.flet.web].pwa_background_color / [tool.flet.web].pwa_theme_color
  3. #FFFFFF / #0175C2

Example#

flet build web --pwa-background-color "#000000" --pwa-theme-color "#FF0000"

[tool.flet.web]
pwa_background_color = "#000000"
pwa_theme_color = "#FF0000"

WASM output#

By default, flet build web enables Flutter's WASM output.

Note

flet build web only.

Resolution order#

The WASM output is disabled in the following order of precedence:

  1. --no-wasm
  2. [tool.flet.web].wasm = false
  3. default: WASM enabled

Example#

flet build web --no-wasm

[tool.flet.web]
wasm = false