flet publish

The flet publish command compiles and packages your Flet app as a standalone static web application that can be deployed to any static hosting service (GitHub Pages, Netlify, Vercel, etc.).

Basic Usage

flet publish [script] [options]

How It Works

flet publish creates a static web application by:

Packaging your Python app and dependencies into a .tar.gz archive
Copying the Flet web runtime (Flutter web + Pyodide)
Configuring the app to run entirely in the browser using WebAssembly
Generating PWA (Progressive Web App) manifests
Outputting everything to the dist/ directory

The result is a collection of static files that can be hosted on any web server.

Examples

Publish Current Directory

flet publish

Publishes main.py from the current directory to dist/.

Publish Specific Script

flet publish app.py

Publish with Custom Output

flet publish --distpath build/web

Publish for GitHub Pages

flet publish --base-url /my-repo/

Publish with Custom PWA Metadata

flet publish \
  --app-name "Task Manager" \
  --app-short-name "Tasks" \
  --app-description "Manage your daily tasks" \
  --pwa-theme-color "#2196F3"

Publish for Offline Use

flet publish --no-cdn

Bundles all dependencies (CanvasKit, Pyodide) for offline deployment.

Arguments

script

string

default:"."

Path to the Python script that starts your Flet app.

flet publish app.py
flet publish src/main.py

If a directory is provided, looks for main.py inside it.

Options

Output

--distpath

string

default:"dist"

Directory where the published web app should be placed.

flet publish --distpath build/web

The directory is cleaned before publishing.

App Metadata

--app-name

string

Full name of the application. Used in PWA metadata and may appear in the install prompt.

flet publish --app-name "My Awesome App"

Falls back to tool.flet.product or project.name in pyproject.toml.

--app-short-name

string

A shorter version of the application name, often used in homescreen icons or install prompts.

flet publish --app-short-name "MyApp"

Falls back to project.name in pyproject.toml.

--app-description

string

Short description of the application. Used in PWA manifests and metadata.

flet publish --app-description "A productivity tool"

Falls back to project.description in pyproject.toml.

PWA Configuration

--pwa-background-color

string

Initial background color of your web app during the loading phase (used in splash screens).

flet publish --pwa-background-color "#ffffff"

Falls back to tool.flet.web.pwa_background_color in pyproject.toml.

--pwa-theme-color

string

Default color of the browser UI (e.g., address bar) when your app is installed as a PWA.

flet publish --pwa-theme-color "#2196F3"

Falls back to tool.flet.web.pwa_theme_color in pyproject.toml.

Web Renderer

--web-renderer

enum

default:"auto"

Flutter web renderer to use.Options:

auto - Automatically choose based on device
canvaskit - WebAssembly-based renderer (best compatibility)
skwasm - Experimental WASM renderer (better performance)

flet publish --web-renderer canvaskit

Can also be set via FLET_WEB_RENDERER environment variable or tool.flet.web.renderer in pyproject.toml.

URL Configuration

--base-url

string

default:"/"

Base URL path to serve the app from. Useful if the app is hosted in a subdirectory.

flet publish --base-url /my-app/

Important: Must start and end with /.Falls back to tool.flet.web.base_url in pyproject.toml.Examples:

Root: / (default)
Subdirectory: /my-app/
GitHub Pages: /repository-name/

--route-url-strategy

enum

default:"path"

Controls how routes are handled in the browser.Options:

path - Uses HTML5 history API (/about)
hash - Uses URL fragments (/#/about)

flet publish --route-url-strategy hash

Use hash when:

Deploying to static hosts without server-side routing
GitHub Pages, Netlify, etc. (unless configured for SPA)

Use path when:

Server can handle SPA routing (returns index.html for all routes)
Cleaner URLs are preferred

Can also be set via FLET_WEB_ROUTE_URL_STRATEGY environment variable or tool.flet.web.route_url_strategy in pyproject.toml.

Assets

-a, --assets

string

Path to a directory containing static assets used by the app (e.g., images, fonts, icons).

flet publish --assets static/

Can also be set via FLET_ASSETS_DIR environment variable.Assets are copied to the dist directory and available at runtime.

Dependencies

--pre

flag

Allow micropip to install pre-release Python packages.

flet publish --pre

Use this if your app depends on a prerelease version of a package.

CDN Options

--no-cdn

flag

Disable loading of CanvasKit, Pyodide, and fonts from CDNs.

flet publish --no-cdn

Use this for:

Full offline deployments
Air-gapped environments
Corporate intranets
Avoiding external dependencies

Note: Significantly increases bundle size (adds ~50-100 MB).Can also be set via setting tool.flet.web.cdn = false in pyproject.toml.

Published Output

The dist/ directory contains:

dist/
├── index.html          # Main HTML file
├── manifest.json       # PWA manifest
├── flutter.js          # Flutter loader
├── flutter_service_worker.js
├── canvaskit/          # Flutter web renderer
├── assets/             # Your app assets
│   └── FontManifest.json
├── app.tar.gz          # Your packaged Python app
└── pyodide/            # Python runtime (if --no-cdn)

Dependency Resolution

The publish command determines Python dependencies from:

pyproject.toml (preferred):

[project]
dependencies = [
    "flet>=0.24.0",
    "requests",
]

Or Poetry format:

[tool.poetry.dependencies]
python = "^3.8"
flet = "^0.24.0"
requests = "^2.31.0"

requirements.txt:
```
flet>=0.24.0
requests
pandas
```
Default: If neither exists, only flet is included.

Dependencies are installed by Pyodide at runtime in the browser.

Deployment Examples

Deploy to GitHub Pages

# Publish with base URL
flet publish --base-url /my-repo/ --route-url-strategy hash

# Copy to gh-pages branch
cd dist
git init
git add .
git commit -m "Deploy"
git branch -M gh-pages
git remote add origin https://github.com/user/my-repo.git
git push -f origin gh-pages

Deploy to Netlify

flet publish
npm install -g netlify-cli
netlify deploy --dir dist --prod

Or use Netlify’s drag-and-drop:

Run flet publish
Go to Netlify Drop
Drag the dist folder

Deploy to Vercel

flet publish
npm install -g vercel
vercel --prod dist

Deploy to Firebase Hosting

flet publish --distpath public
firebase init hosting
firebase deploy

Deploy to AWS S3

flet publish
aws s3 sync dist/ s3://my-bucket --delete
aws s3 website s3://my-bucket --index-document index.html

Self-Hosted Server

flet publish
flet serve

Or copy dist/ to your web server:

flet publish
scp -r dist/* user@server:/var/www/html/

Configuration File

Configure publish settings in pyproject.toml:

[project]
name = "my-app"
version = "1.0.0"
description = "My awesome Flet app"

[tool.flet]
product = "My Awesome App"

[tool.flet.web]
renderer = "canvaskit"
route_url_strategy = "path"
base_url = "/"
pwa_background_color = "#ffffff"
pwa_theme_color = "#2196F3"
cdn = true

Command-line arguments override pyproject.toml settings.

Testing Published App

After publishing, test locally:

flet publish
flet serve

Open http://localhost:8000 in your browser. Or use Python’s built-in server:

cd dist
python -m http.server 8000

Note: Some features (like Pyodide) require special CORS headers. Use flet serve for proper testing.

PWA Features

Published apps are Progressive Web Apps (PWA) and can be:

Installed on desktop and mobile devices
Run offline (after initial load)
Added to home screen on mobile
Run in standalone mode (without browser UI)

Install Prompt

Users can install your app:

Visit the published URL
Browser shows “Install” or “Add to Home Screen” prompt
App runs as standalone application

Offline Support

Service worker enables offline functionality:

App shell cached on first visit
Works without internet after initial load
Python code runs entirely in browser

Package Exclusions

These files/directories are automatically excluded from app.tar.gz:

Hidden files/directories (.git, .env, etc.)
__pycache__
requirements.txt (replaced with generated one)
Assets directory (copied separately)
Dist directory (to avoid recursion)

Performance Optimization

Reduce Bundle Size

Use CDN (default):
```
flet publish  # ~2-5 MB
```
Minimize dependencies: Only include required packages in pyproject.toml.
Optimize assets:
- Compress images
- Use web-friendly formats (WebP, AVIF)
- Remove unused fonts

Improve Load Time

Use canvaskit renderer:
```
flet publish --web-renderer canvaskit
```
Enable CDN: Faster than bundling dependencies.
Compress assets: Configure server gzip/brotli compression.

Troubleshooting

App Doesn’t Load

Check browser console for errors. Common issues:

Incorrect --base-url
CORS headers missing (use flet serve for testing)
Missing dependencies

Dependencies Not Installing

Ensure packages are Pyodide-compatible: Not all Python packages work in browser. Check Pyodide package list.

Routing Not Working

Use hash strategy for static hosts:

flet publish --route-url-strategy hash

Large Bundle Size

Avoid --no-cdn unless necessary:

# Good (small)
flet publish

# Large (50-100 MB extra)
flet publish --no-cdn

Assets Not Loading

Verify assets path:

flet publish --assets ./assets

Ensure assets directory exists and contains files.

Comparison with flet build web

Both commands create web apps, but with different approaches:

Feature	`flet publish`	`flet build web`
Runtime	Python in browser (Pyodide)	Compiled Dart
Bundle size	Larger (~50 MB with CDN)	Smaller (~5-10 MB)
Deployment	Static hosting	Static hosting
Load time	Slower (loads Python)	Faster
Python features	Full Python support	Limited
Offline	After first load	After first load
Best for	Full Python apps, rapid development	Production, performance-critical

Recommendation: Use flet build web for production deployments when possible. Use flet publish for rapid prototyping or when full Python compatibility is required.

Next Steps

Serve Command

Test published apps locally

Build Web

Build optimized web apps

Deployment Guide

Deploy to various platforms

PWA Guide

Progressive Web App features

Get Started

Core Concepts

Building Apps

Controls

CLI

Advanced

​Basic Usage

​How It Works

​Examples

​Publish Current Directory

​Publish Specific Script

​Publish with Custom Output

​Publish for GitHub Pages

​Publish with Custom PWA Metadata

​Publish for Offline Use

​Arguments

​Options

​Output

​App Metadata

​PWA Configuration

​Web Renderer

​URL Configuration

​Assets

​Dependencies

​CDN Options

​Published Output

​Dependency Resolution

​Deployment Examples

​Deploy to GitHub Pages

​Deploy to Netlify

​Deploy to Vercel

​Deploy to Firebase Hosting

​Deploy to AWS S3

​Self-Hosted Server

​Configuration File

​Testing Published App

​PWA Features

​Install Prompt

​Offline Support

​Package Exclusions

​Performance Optimization

​Reduce Bundle Size

​Improve Load Time

​Troubleshooting

​App Doesn’t Load

​Dependencies Not Installing

​Routing Not Working

​Large Bundle Size

​Assets Not Loading

​Comparison with flet build web

​Next Steps

Serve Command

Build Web

Deployment Guide

PWA Guide

Build docs developers (and LLMs) love

Basic Usage

How It Works

Examples

Publish Current Directory

Publish Specific Script

Publish with Custom Output

Publish for GitHub Pages

Publish with Custom PWA Metadata

Publish for Offline Use

Arguments

Options

Output

App Metadata

PWA Configuration

Web Renderer

URL Configuration

Assets

Dependencies

CDN Options

Published Output

Dependency Resolution

Deployment Examples

Deploy to GitHub Pages

Deploy to Netlify

Deploy to Vercel

Deploy to Firebase Hosting

Deploy to AWS S3

Self-Hosted Server

Configuration File

Testing Published App

PWA Features

Install Prompt

Offline Support

Package Exclusions

Performance Optimization

Reduce Bundle Size

Improve Load Time

Troubleshooting

App Doesn’t Load

Dependencies Not Installing

Routing Not Working

Large Bundle Size

Assets Not Loading

Comparison with flet build web

Next Steps