Skip to main content

Running a Flet app (Hot Reload)

Flet apps can be executed as either desktop or web applications using the flet run command. Doing so will start the app in a native OS window or a web browser, respectively, with hot reload enabled to view changes in real-time.

Desktop app​

To run Flet app as a desktop app, use the following command:

uv run flet run

When you run the command without any arguments, main.py script in the current directory will be executed, by default.

If you need to provide a different path, use the following command:

uv run flet run [script]

Where [script] is a relative (ex: counter.py) or absolute (ex: /Users/john/projects/flet-app/main.py) path to the Python script you want to run.

The app will be started in a native OS window:

  • macOS

    macOS

  • Windows

    windows
How the desktop client is selected

A desktop Flet app has two parts: your Python code and a Flutter client that displays the UI. When you run flet run or start a script with python main.py that calls ft.run(main), Flet looks for a desktop client in this order:

  1. A client from a previous flet build in build/<platform> under the current working directory, such as build/windows, build/macos, or build/linux.
  2. A client in the directory specified by FLET_VIEW_PATH.
  3. The standard pre-built Flet client cached in ~/.flet/client/, downloading it if needed.

Reusing a locally built client lets you run an app with custom Flutter extensions. Your current Python source still runs: Flet launches the client and connects it to that Python process. For example, after flet build windows, you can edit main.py and run flet run main.py without rebuilding. The executable in build/windows supplies the UI client; the Python code bundled during the build is not used in this mode.

Rebuild when you add or change Flutter extensions. Python-only changes do not require rebuilding the client. See Creating an Extension for an example of this workflow.

To use the standard client again, move or rename the corresponding build/<platform> directory and unset FLET_VIEW_PATH if it is set. Setting FLET_VIEW_PATH alone does not override a client found in build/<platform>.

note

Opening the built executable directly runs the packaged app, including the Python code from the build. Rebuild to include Python changes in that packaged app.

Web app​

To run Flet app as a web app, use the --web (or -w) option:

uv run flet run --web [script]

A new browser window/tab will be opened and the app will be using a random TCP port:

Web
Running Flet app as a web app

Passing arguments to your app​

Anything after a -- separator is passed through to your app script instead of being interpreted by Flet, and shows up there as sys.argv[1:]:

uv run flet run --web [script] -- --dataset big.csv --verbose

Your app reads them as it would when started with python:

main.py
import argparse
import sys

import flet as ft

parser = argparse.ArgumentParser()
parser.add_argument("--dataset", default="small.csv")
parser.add_argument("--verbose", action="store_true")
options = parser.parse_args(sys.argv[1:])


def main(page: ft.Page):
    page.add(ft.Text(f"Dataset: {options.dataset}"))


ft.run(main)

The -- separator is what keeps your app's arguments from being read as Flet's own - without it, flet run main.py --verbose fails because --verbose is not a flet run option. Arguments that don't start with a - can be passed without a separator, e.g. flet run main.py big.csv.

note

The same arguments are re-applied every time the app is hot reloaded, and they are passed through in all run modes: desktop, --web, --ios and --android.

Watching for changes​

By default, Flet will watch the script file that was run and reload the app whenever the contents of this file are modified+saved, but will not watch for changes in other files.

To modify this behavior, you can use one or more of these flet run options:

  • -d or --directory to watch for changes in the [script]s directory only
  • -r or --recursive to watch for changes in the [script]s directory and all sub-directories recursively
Example
uv run flet run --recursive [script]