Skip to main content

flet debug

Run a Flet Python app in debug mode on a specified platform (desktop, web, mobile).

Arguments after -- are passed down to the underlying flutter run.

Detailed usage guide: https://flet.dev/blog/flet-debug-the-new-cli-for-testing-flet-apps-on-mobile-devices.

Usage​

flet debug [-h] [-v] [--device-id DEVICE_ID] [--show-devices] [--release]
                [--route ROUTE] [--arch TARGET_ARCH [TARGET_ARCH ...]]
                [--exclude EXCLUDE [EXCLUDE ...]]
                [--include INCLUDE [INCLUDE ...]] [--no-default-excludes]
                [--project PROJECT_NAME] [--artifact ARTIFACT_NAME]
                [--description DESCRIPTION] [--product PRODUCT_NAME]
                [--org ORG_NAME] [--bundle-id BUNDLE_ID]
                [--company COMPANY_NAME] [--copyright COPYRIGHT]
                [--android-adaptive-icon-background ANDROID_ADAPTIVE_ICON_BACKGROUND]
                [--linux-categories LINUX_CATEGORIES [LINUX_CATEGORIES ...]]
                [--splash-color SPLASH_COLOR]
                [--splash-dark-color SPLASH_DARK_COLOR] [--no-web-splash]
                [--no-ios-splash] [--no-android-splash]
                [--ios-team-id IOS_TEAM_ID]
                [--ios-export-method IOS_EXPORT_METHOD]
                [--ios-provisioning-profile IOS_PROVISIONING_PROFILE]
                [--ios-signing-certificate IOS_SIGNING_CERTIFICATE]
                [--base-url BASE_URL] [--web-renderer {auto,canvaskit,skwasm}]
                [--route-url-strategy {path,hash}]
                [--pwa-background-color PWA_BACKGROUND_COLOR]
                [--pwa-theme-color PWA_THEME_COLOR]
                [--pwa-short-name PWA_SHORT_NAME] [--no-wasm] [--no-cdn]
                [--split-per-abi]
                [--android-legacy-packaging | --no-android-legacy-packaging]
                [--compile-app | --no-compile-app]
                [--compile-packages | --no-compile-packages]
                [--swift-package-manager | --no-swift-package-manager]
                [--impeller | --no-impeller] [--cleanup-app]
                [--cleanup-app-files CLEANUP_APP_FILES [CLEANUP_APP_FILES ...]]
                [--cleanup-packages]
                [--cleanup-package-files CLEANUP_PACKAGE_FILES [CLEANUP_PACKAGE_FILES ...]]
                [--flutter-build-args [FLUTTER_BUILD_ARGS ...]]
                [--source-packages SOURCE_PACKAGES [SOURCE_PACKAGES ...]]
                [--android-extract-packages ANDROID_EXTRACT_PACKAGES [ANDROID_EXTRACT_PACKAGES ...]]
                [--python-version PYTHON_VERSION]
                [--info-plist INFO_PLIST [INFO_PLIST ...]]
                [--macos-entitlements MACOS_ENTITLEMENTS [MACOS_ENTITLEMENTS ...]]
                [--ios-entitlements IOS_ENTITLEMENTS [IOS_ENTITLEMENTS ...]]
                [--android-features ANDROID_FEATURES [ANDROID_FEATURES ...]]
                [--android-permissions ANDROID_PERMISSIONS [ANDROID_PERMISSIONS ...]]
                [--android-meta-data ANDROID_META_DATA [ANDROID_META_DATA ...]]
                [--permissions {location,camera,microphone,photo_library,biometric} [{location,camera,microphone,photo_library,biometric} ...]]
                [--deep-linking-scheme DEEP_LINKING_SCHEME]
                [--deep-linking-host DEEP_LINKING_HOST]
                [--android-signing-key-store ANDROID_SIGNING_KEY_STORE]
                [--android-signing-key-store-password ANDROID_SIGNING_KEY_STORE_PASSWORD]
                [--android-signing-key-password ANDROID_SIGNING_KEY_PASSWORD]
                [--android-signing-key-alias ANDROID_SIGNING_KEY_ALIAS]
                [--macos-signing-identity MACOS_SIGNING_IDENTITY]
                [--macos-distribution {none,developer-id,app-store}]
                [--macos-notary-profile MACOS_NOTARY_PROFILE]
                [--macos-provisioning-profile MACOS_PROVISIONING_PROFILE]
                [--macos-installer-identity MACOS_INSTALLER_IDENTITY]
                [--build-number BUILD_NUMBER] [--build-version BUILD_VERSION]
                [--module-name MODULE_NAME] [--template TEMPLATE]
                [--template-dir TEMPLATE_DIR] [--template-ref TEMPLATE_REF]
                [--show-platform-matrix] [--log-format {rich,plain,github}]
                [--no-rich-output] [--yes] [--skip-flutter-doctor]
                [{macos,linux,windows,web,ios,android}] [python_app_path]

Positional arguments​

platform​

The target platform to run the app on.

Possible values: android, ios, linux, macos, web, windows

Required: false

python_app_path​

Path to a directory with a Flet Python program.

Default: .

Options​

--android-adaptive-icon-background​

The color to be used to fill out the background of Android adaptive icons.

--android-extract-packages​

Android only: Python packages (relative paths) to ship extracted to disk instead of inside the app zip — for packages that read bundled data via file / pkg_resources rather than importlib.resources.

Value: ANDROID_EXTRACT_PACKAGES+

--android-features​

The list of <feature_name>=true|false features to add to AndroidManifest.xml (android only); can be used multiple times.

Value: ANDROID_FEATURES+

--android-legacy-packaging​

Use legacy Android native-library packaging: extract .so to disk at install time instead of memory-mapping them directly from the APK. Off by default (modern packaging). Enabling it makes the raw .apk file smaller for side-loading, at the cost of a larger on-device install size and slower native-library loading (Android only).

Aliases: --no-android-legacy-packaging

--android-meta-data​

The list of <name>=<value> app meta-data entries to add to AndroidManifest.xml (android only); can be used multiple times.

Value: ANDROID_META_DATA+

--android-permissions​

The list of <permission_name>=true|false permissions to add to AndroidManifest.xml (android only); can be used multiple times.

Value: ANDROID_PERMISSIONS+

--android-signing-key-alias​

Android signing key alias.

Environment variable: FLET_ANDROID_SIGNING_KEY_ALIAS

--android-signing-key-password​

Android signing key password.

Environment variable: FLET_ANDROID_SIGNING_KEY_PASSWORD

--android-signing-key-store​

Path to an upload keystore .jks file for Android apps.

Environment variable: FLET_ANDROID_SIGNING_KEY_STORE

--android-signing-key-store-password​

Android signing store password.

Environment variable: FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD

--arch​

Build for specific CPU architectures (used in macOS and Android builds only). Android: arm64-v8a, armeabi-v7a, x86_64; macOS: arm64, x86_64. Example: --arch arm64-v8a.

Value: TARGET_ARCH+

--artifact​

Executable or bundle name on disk.

--base-url​

Base URL from which the app is served (web only).

--build-number​

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

Value: BUILD_NUMBER <int>

--build-version​

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

--bundle-id​

Bundle ID for the application, e.g. com.mycompany.app-name. It is used as an iOS, Android, macOS and Linux bundle ID.

--cleanup-app​

Remove unnecessary app files upon packaging.

--cleanup-app-files​

The list of globs to delete extra app files and directories.

Value: CLEANUP_APP_FILES+

--cleanup-package-files​

The list of globs to delete extra package files and directories.

Value: CLEANUP_PACKAGE_FILES+

--cleanup-packages​

Remove unnecessary package files upon packaging.

--company​

Company name to display in about app dialogs.

--compile-app​

Pre-compile app's .py files to .pyc (on by default; use --no-compile-app to disable).

Aliases: --no-compile-app

--compile-packages​

Pre-compile site packages' .py files to .pyc (on by default; use --no-compile-packages to disable).

Aliases: --no-compile-packages

--copyright​

Copyright text to display in about app dialogs.

--deep-linking-host​

Deep linking URL host for iOS and Android builds; optional except for http and https schemes. Requires --deep-linking-scheme.

--deep-linking-scheme​

Deep linking URL scheme to configure for iOS and Android builds, e.g. myapp or https.

--description​

Short description of the application.

--device-id​

Device ID to run the app on for iOS and Android builds.

Aliases: -d

--exclude​

Files and/or directories to exclude from the package; can be used multiple times.

Value: EXCLUDE+

--flutter-build-args​

Additional arguments for flutter build command. Attach an argument that starts with - using =, e.g. --flutter-build-args=--obfuscate, or pass the arguments after --.

Value: FLUTTER_BUILD_ARGS*

--help​

Show this help message and exit.

Aliases: -h

--impeller​

Render with Impeller, Flutter's default renderer (on by default). Use --no-impeller (or impeller = false under [tool.flet]) to render with Skia on macOS, Windows, Linux and Android; iOS always uses Impeller and web always uses Skia.

Aliases: --no-impeller

--include​

Files and/or directories excluded by default to package anyway (e.g. .env); can be used multiple times.

Value: INCLUDE+

--info-plist​

The list of <key>=<value> pairs to add to Info.plist. Values can be booleans, strings, numbers, TOML arrays, or TOML inline tables (macos, ipa and ios-simulator only); can be used multiple times.

Value: INFO_PLIST+

--ios-entitlements​

The list of <key>=<value> entitlements. Values can be booleans, strings, numbers, TOML arrays, or TOML inline tables (ipa and ios-simulator only); can be used multiple times.

Value: IOS_ENTITLEMENTS+

--ios-export-method​

Export method for iOS app bundle (default: debugging).

--ios-provisioning-profile​

Provisioning profile name or UUID that should be used to sign and export iOS app bundle.

--ios-signing-certificate​

Signing certificate name, SHA-1 hash, or automatic selector to use for signing iOS app bundle.

--ios-team-id​

Apple developer team ID for signing iOS app bundle (ipa only).

--linux-categories​

The list of freedesktop application categories for the generated desktop entry, e.g. Education or Game (linux only); can be used multiple times.

Value: LINUX_CATEGORIES+

--log-format​

Output format: rich shows a live spinner, plain prints plain text lines, github prints plain text plus GitHub Actions workflow commands - a collapsible group per build step and annotations for warnings and errors. Defaults to github when GITHUB_ACTIONS=true, otherwise rich.

Possible values: github, plain, rich

Environment variable: FLET_CLI_LOG_FORMAT

--macos-distribution​

Distribution channel to sign and package for: 'developer-id' signs with the hardened runtime, notarizes and staples for direct distribution; 'app-store' produces a sandboxed build with an embedded provisioning profile and a signed installer .pkg for App Store Connect / TestFlight; 'none' (default) signs only when a signing identity is configured (macos only).

Possible values: app-store, developer-id, none

--macos-entitlements​

The list of <key>=<value> entitlements. Values can be booleans, strings, numbers, TOML arrays, or TOML inline tables (macos only); can be used multiple times.

Value: MACOS_ENTITLEMENTS+

--macos-installer-identity​

"3rd Party Mac Developer Installer" / "Mac Installer Distribution" certificate name or SHA-1 fingerprint used to sign the App Store installer package; when not configured, the only installer certificate in the keychain is auto-discovered (macos only).

Environment variable: FLET_MACOS_INSTALLER_IDENTITY

--macos-notary-profile​

Keychain profile name created with xcrun notarytool store-credentials to authenticate with the Apple notary service; alternatively set the APPLE_API_KEY, APPLE_API_KEY_ID and APPLE_API_ISSUER environment variables (macos only).

Environment variable: FLET_MACOS_NOTARY_PROFILE

--macos-provisioning-profile​

Path to a Mac App Store provisioning profile (.provisionprofile) to embed at Contents/embedded.provisionprofile; required for App Store builds (macos only).

Environment variable: FLET_MACOS_PROVISIONING_PROFILE

--macos-signing-identity​

"Developer ID Application" (direct distribution) or "Apple Distribution" (App Store) certificate name, its SHA-1 fingerprint, or "-" for ad-hoc, used to code-sign the app bundle; when not configured (CLI, pyproject.toml, or env), developer-id and app-store distribution builds auto-discover the only certificate of the required type (macos only).

Environment variable: FLET_MACOS_SIGNING_IDENTITY

--module-name​

Python module name with an app entry point.

--no-android-splash​

Disable splash screen on Android platform.

--no-cdn​

Disable loading of CanvasKit, Pyodide and fonts from CDN.

Environment variable: FLET_WEB_NO_CDN

--no-default-excludes​

Package hidden top-level files and directories, virtual environments and __pycache__ directories instead of excluding them.

--no-ios-splash​

Disable splash screen on iOS platform.

--no-rich-output​

Disable rich output and prefer plain text, same as --log-format plain. Useful on Windows builds.

Environment variable: FLET_CLI_NO_RICH_OUTPUT

--swift-package-manager​

Integrate the embedded Python runtime via Swift Package Manager (default) or CocoaPods for iOS/macOS builds. On by default, matching Flutter 3.44+ which uses SPM by default (other non-SPM plugins still build with CocoaPods alongside it). Use --no-swift-package-manager (or swift_package_manager = false under [tool.flet]) only if you've disabled Swift Package Manager in Flutter.

Aliases: --no-swift-package-manager

--no-wasm​

Disable WASM target for web build (web only).

--no-web-splash​

Disable splash screen on web platform.

--org​

Organization name in reverse domain name notation, e.g. com.mycompany, combined with project name and used in bundle IDs and signing.

--permissions​

The list of pre-defined cross-platform permissions for iOS, Android and macOS builds.

Possible values: biometric, camera, location, microphone, photo_library

--product​

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

--project​

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

--pwa-background-color​

Initial background color for your web app (web only).

--pwa-short-name​

Short name of your web app, shown under its icon when installed, e.g. on the iOS Home Screen. Defaults to the product name (web only).

--pwa-theme-color​

Default color for your web app's user interface (web only).

--python-version​

Python version to bundle (e.g. 3.13). Defaults to the latest supported version, or is parsed from project.requires-python.

--release​

Build the app in release mode.

--route​

Route to open the app on for web, iOS and Android builds.

--route-url-strategy​

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

Possible values: hash, path

Environment variable: FLET_WEB_ROUTE_URL_STRATEGY

--show-devices​

Show connected devices for iOS and Android builds.

--show-platform-matrix​

Display the build platform matrix in a table, then exit.

--skip-flutter-doctor​

Skip running Flutter doctor upon failed builds.

Environment variable: FLET_CLI_SKIP_FLUTTER_DOCTOR

--source-packages​

The list of Python packages to install from source distributions.

Value: SOURCE_PACKAGES+

--splash-color​

Background color of app splash screen on iOS, Android and web.

--splash-dark-color​

Background color in dark mode of app splash screen on iOS, Android and web.

--split-per-abi​

Split the APKs per ABIs (Android only).

--template​

Directory containing Flutter bootstrap template, or a URL to a git repository template.

--template-dir​

Relative path to a Flutter bootstrap template in a repository.

--template-ref​

The branch, tag or commit ID to checkout after cloning the repository with Flutter bootstrap template.

--verbose​

Enable verbose output. Use -v for standard verbose logging and -vv for more detailed output.

Aliases: -v

--web-renderer​

Flutter web renderer to use (web only), default: canvaskit.

Possible values: auto, canvaskit, skwasm

Environment variable: FLET_WEB_RENDERER

--yes​

Answer yes to all prompts (install dependencies without confirmation).