flet build - Flet

The flet build command compiles your Flet Python app into a platform-specific executable or installable bundle. It supports building for desktop (macOS, Linux, Windows), web, Android (APK/AAB), and iOS (IPA).

Basic Usage

flet build <target_platform> [python_app_path] [options]

Target Platforms

The following target platforms are available:

target_platform

enum

required

The platform or package type to build:

macos - macOS application bundle (.app)
linux - Linux executable bundle
windows - Windows executable
web - Progressive Web App (PWA)
apk - Android application package
aab - Android App Bundle (for Play Store)
ipa - iOS application archive
ios-simulator - iOS app for simulator testing

Build Platform Matrix

Not all platforms can be built from every operating system:

Command	Can be run on
`flet build macos`	macOS only
`flet build linux`	Linux only
`flet build windows`	Windows only
`flet build web`	macOS, Windows, Linux
`flet build apk`	macOS, Windows, Linux
`flet build aab`	macOS, Windows, Linux
`flet build ipa`	macOS only
`flet build ios-simulator`	macOS only

Examples

Build for macOS

flet build macos

Creates a .app bundle in build/macos/.

Build for Windows

flet build windows

Creates an executable in build/windows/.

Build Web App

flet build web

Generates a static web app in build/web/.

Build Android APK

flet build apk

Creates an APK in build/apk/.

Build iOS App

flet build ipa --ios-team-id XXXXXXXXXX

Builds a signed IPA for distribution.

Build for Multiple Architectures

flet build macos --arch universal
flet build apk --arch arm64-v8a armeabi-v7a

Arguments

python_app_path

string

default:"."

Path to a directory with a Flet Python program. If omitted, uses the current directory.

flet build macos ./src

Common Options

Output Directory

-o, --output

string

Output directory for the final executable/bundle.Default: <python_app_path>/build/<target_platform>

flet build web --output dist/web

Project Metadata

--project

string

Project name for bundle IDs and identifiers. Used as the default for artifact and product names.

flet build apk --project my-app

Falls back to project.name in pyproject.toml.

--product

string

Display name shown in app launchers, window titles, and about dialogs.

flet build macos --product "My Awesome App"

Falls back to tool.flet.product in pyproject.toml.

--description

string

Short description of the application.

flet build web --description "A productivity tool"

Falls back to project.description in pyproject.toml.

--org

string

Organization name in reverse domain notation (e.g., com.mycompany).

flet build apk --org com.example

Used in bundle IDs: com.example.my-app

--company

string

Company name to display in about app dialogs.

flet build windows --company "ACME Corporation"

Versioning

--build-number

integer

Build number - an identifier used as an internal version number.

flet build apk --build-number 42

On Android, this becomes versionCode. On iOS, CFBundleVersion.Falls back to tool.flet.build_number in pyproject.toml.

--build-version

string

Build version - a x.y.z string used as the version number shown to users.

flet build apk --build-version 1.2.3

Falls back to project.version or tool.poetry.version in pyproject.toml.

Architecture

--arch

string[]

Build for specific CPU architectures. Can be specified multiple times.macOS:

x64 - Intel 64-bit
arm64 - Apple Silicon
universal - Universal binary (both architectures)

Android:

arm64-v8a - 64-bit ARM
armeabi-v7a - 32-bit ARM
x86_64 - 64-bit Intel/AMD

flet build macos --arch universal
flet build apk --arch arm64-v8a armeabi-v7a

Platform-Specific Options

Android Options

--split-per-abi

flag

Split the APKs per ABI (Application Binary Interface).

flet build apk --split-per-abi

Creates separate APK files for each architecture, reducing download size.

--android-adaptive-icon-background

string

Background color for Android adaptive icons.

flet build apk --android-adaptive-icon-background "#FF5722"

--android-permissions

string[]

Permissions to add to AndroidManifest.xml.

flet build apk --android-permissions android.permission.CAMERA=True

Format: <permission_name>=True|False

--android-features

string[]

Features to add to AndroidManifest.xml.

flet build apk --android-features android.hardware.camera=True

Format: <feature_name>=True|False

Android Signing

--android-signing-key-store

string

Path to an upload keystore .jks file.

flet build apk --android-signing-key-store upload-keystore.jks

Can also be set via FLET_ANDROID_SIGNING_KEY_STORE environment variable.

--android-signing-key-store-password

string

Android signing store password.

flet build apk --android-signing-key-store-password mypassword

Can also be set via FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD environment variable.

--android-signing-key-password

string

Android signing key password.Can also be set via FLET_ANDROID_SIGNING_KEY_PASSWORD environment variable.

--android-signing-key-alias

string

Android signing key alias.Can also be set via FLET_ANDROID_SIGNING_KEY_ALIAS environment variable.

iOS Options

--ios-team-id

string

Apple Developer Team ID for signing iOS app bundle.

flet build ipa --ios-team-id XXXXXXXXXX

Required for building .ipa files.

--ios-provisioning-profile

string

Provisioning profile name or UUID for signing and exporting iOS app bundle.

flet build ipa --ios-provisioning-profile "My App Profile"

--ios-export-method

string

Export method for iOS app bundle.Options: app-store, ad-hoc, enterprise, developmentDefault: development

flet build ipa --ios-export-method app-store

--ios-signing-certificate

string

Signing certificate name, SHA-1 hash, or automatic selector.

flet build ipa --ios-signing-certificate "iPhone Distribution"

Web Options

--base-url

string

Base URL from which the app is served.

flet build web --base-url /my-app/

Useful if hosting in a subdirectory.Falls back to tool.flet.web.base_url in pyproject.toml.

--web-renderer

enum

Flutter web renderer to use.Options: auto, canvaskit, skwasmDefault: auto

flet build web --web-renderer canvaskit

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

Can also be set via FLET_WEB_RENDERER environment variable.

--route-url-strategy

enum

Controls how routes are handled in the browser.Options: path, hashDefault: path

flet build web --route-url-strategy hash

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

Can also be set via FLET_WEB_ROUTE_URL_STRATEGY environment variable.

--pwa-background-color

string

Initial background color for your web app during loading.

flet build web --pwa-background-color "#ffffff"

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

--pwa-theme-color

string

Default color for your web app’s user interface (browser UI).

flet build web --pwa-theme-color "#2196F3"

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

--no-cdn

flag

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

flet build web --no-cdn

Use for offline deployments or air-gapped environments.Can also be set via FLET_WEB_NO_CDN environment variable.

--no-wasm

flag

Disable WASM target for web build.

flet build web --no-wasm

macOS/iOS Options

--info-plist

string[]

Key-value pairs to add to Info.plist.

flet build macos --info-plist NSCameraUsageDescription="This app uses the camera"

Format: <key>=<value>|True|False

--macos-entitlements

string[]

Entitlements for macOS builds.

flet build macos --macos-entitlements com.apple.security.device.camera=True

Format: <key>=<value>|True|False

Advanced Options

Bundle ID

--bundle-id

string

Bundle ID for the application (e.g., com.mycompany.app-name).

flet build apk --bundle-id com.example.myapp

Used for iOS, Android, macOS, and Linux.

Splash Screen

--splash-color

string

Background color of app splash screen.

flet build apk --splash-color "#2196F3"

--splash-dark-color

string

Background color in dark mode.

flet build apk --splash-dark-color "#1976D2"

--no-web-splash

flag

Disable splash screen on web platform.

--no-ios-splash

flag

Disable splash screen on iOS platform.

--no-android-splash

flag

Disable splash screen on Android platform.

Permissions

--permissions

enum[]

Pre-defined cross-platform permissions.Options: location, camera, microphone, photo_library

flet build apk --permissions camera location

Automatically adds platform-specific permission declarations.

Deep Linking

--deep-linking-scheme

string

Deep linking URL scheme (e.g., https or myapp).

flet build apk --deep-linking-scheme myapp

--deep-linking-host

string

Deep linking URL host.

flet build apk --deep-linking-host example.com

Python Compilation

--compile-app

flag

Pre-compile app’s .py files to .pyc.

flet build apk --compile-app

Slightly improves startup time.

--compile-packages

flag

Pre-compile site packages’ .py files to .pyc.

flet build apk --compile-packages

Cleanup Options

--cleanup-app

flag

Remove unnecessary app files upon packaging.

flet build windows --cleanup-app

--cleanup-packages

flag

Remove unnecessary package files upon packaging.

flet build windows --cleanup-packages

--exclude

string[]

Files and/or directories to exclude from the package.

flet build web --exclude tests docs *.md

Flutter Options

--flutter-build-args

string[]

Additional arguments for the flutter build command.

flet build apk --flutter-build-args --dart-define=API_KEY=abc123

Build Cache

--clear-cache

flag

Remove any existing build cache before starting the build process.

flet build macos --clear-cache

Useful when builds are failing due to cached state.

Configuration File

Many build options can be set in pyproject.toml:

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

[tool.flet]
product = "My Awesome App"
org_name = "com.example"
company = "Example Corp"
copyright = "Copyright (c) 2024 Example Corp"

[tool.flet.build]
build_number = 1

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

[tool.flet.android]
permissions = ["camera", "location"]

[tool.flet.ios]
team_id = "XXXXXXXXXX"

[tool.flet.macos]
entitlements = { "com.apple.security.device.camera" = true }

Command-line arguments override pyproject.toml settings.

Build Output

Build artifacts are placed in:

build/
├── macos/
│   └── Build/Products/Release/MyApp.app
├── windows/
│   └── x64/runner/Release/
├── linux/
│   └── x64/release/bundle/
├── web/
│   ├── index.html
│   └── ...
├── apk/
│   └── app-release.apk
├── aab/
│   └── app-release.aab
└── ipa/
    └── MyApp.ipa

Example Workflows

Build Desktop App with Custom Icon

flet build macos \
  --product "My App" \
  --org com.example \
  --build-version 1.2.3 \
  --build-number 42

Build Signed Android APK

flet build apk \
  --build-version 1.0.0 \
  --build-number 1 \
  --android-signing-key-store release.jks \
  --android-signing-key-alias upload \
  --android-permissions camera location

Build Web App for GitHub Pages

flet build web \
  --base-url /my-repo/ \
  --web-renderer canvaskit \
  --route-url-strategy hash

Build iOS App for App Store

flet build ipa \
  --ios-team-id XXXXXXXXXX \
  --ios-export-method app-store \
  --build-version 1.0.0 \
  --build-number 1

Troubleshooting

Build Fails with Cache Errors

flet build macos --clear-cache

iOS Build Fails Without Team ID

For .ipa builds, you must provide --ios-team-id:

flet build ipa --ios-team-id XXXXXXXXXX

Android Build Not Signed

Provide signing credentials:

export FLET_ANDROID_SIGNING_KEY_STORE=release.jks
export FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD=storepass
export FLET_ANDROID_SIGNING_KEY_PASSWORD=keypass
export FLET_ANDROID_SIGNING_KEY_ALIAS=upload

flet build apk

Next Steps

Publish Command

Deploy web apps

Pack Command

PyInstaller packaging

Distribution Guide

Learn about app distribution

Icons & Splash

Customize app appearance

Get Started

Core Concepts

Building Apps

Controls

CLI

Advanced

​Basic Usage

​Target Platforms

​Build Platform Matrix

​Examples

​Build for macOS

​Build for Windows

​Build Web App

​Build Android APK

​Build iOS App

​Build for Multiple Architectures

​Arguments

​Common Options

​Output Directory

​Project Metadata

​Versioning

​Architecture

​Platform-Specific Options

​Android Options

​Android Signing

​iOS Options

​Web Options

​macOS/iOS Options

​Advanced Options

​Bundle ID

​Splash Screen

​Permissions

​Deep Linking

​Python Compilation

​Cleanup Options

​Flutter Options

​Build Cache

​Configuration File

​Build Output

​Example Workflows

​Build Desktop App with Custom Icon

​Build Signed Android APK

​Build Web App for GitHub Pages

​Build iOS App for App Store

​Troubleshooting

​Build Fails with Cache Errors

​iOS Build Fails Without Team ID

​Android Build Not Signed

​Next Steps

Publish Command

Pack Command

Distribution Guide

Icons & Splash

Build docs developers (and LLMs) love

Basic Usage

Target Platforms

Build Platform Matrix

Examples

Build for macOS

Build for Windows

Build Web App

Build Android APK

Build iOS App

Build for Multiple Architectures

Arguments

Common Options

Output Directory

Project Metadata

Versioning

Architecture

Platform-Specific Options

Android Options

Android Signing

iOS Options

Web Options

macOS/iOS Options

Advanced Options

Bundle ID

Splash Screen

Permissions

Deep Linking

Python Compilation

Cleanup Options

Flutter Options

Build Cache

Configuration File

Build Output

Example Workflows

Build Desktop App with Custom Icon

Build Signed Android APK

Build Web App for GitHub Pages

Build iOS App for App Store

Troubleshooting

Build Fails with Cache Errors

iOS Build Fails Without Team ID

Android Build Not Signed

Next Steps