Skip to content

Guidelines#

Thank you for your interest in contributing to Flet!

Clone repo#

git clone https://github.com/flet-dev/flet

Python SDK#

Install uv#

Windows#

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Be sure to add %USERPROFILE%\AppData\Roaming\Python\Scripts to PATH.

macOS/Linux#

curl -LsSf https://astral.sh/uv/install.sh | sh

Open worker directory#

cd sdk/python

Install dependencies#

To install all Flet dependencies and enable the project as editable package run:

uv sync

Check the installation#

Create hello.py file with a minimal Flet program:

import flet
from flet import Page, Text

def main(page: Page):
    page.add(Text("Hello, world!"))

flet.app(target=main)

and then run it:

uv run python hello.py

During the first run Flet Client (flet) executable will be downloaded from Flet GitHub releases to a user temp directory and then started from there. The version of release to download from is taken from flet/version.py file.

You should see a new native OS window opened with "Hello, world!" in it.

Running tests#

Pytest should be run with uv run:

uv run pytest

Code formatting#

The project uses Black formatting style. All .py files in a PR must be black-formatted.

Install black extension for Visualtudio Code: https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter

IDE-specific Black integration guides:

Type checking#

Enable "pylance" type checking in VS Code.

Open user settings, search by "pylance", scroll down to Python > Analysis: Type checking mode section. Enable basic mode.

Sort imports on Save#

Install isort extension for imports formatting: https://marketplace.visualstudio.com/items?itemName=ms-python.isort

pre-commit#

pre-commit is a dev dependency of Flet and is automatically installed by uv sync. To install the pre-commit hooks run: uv run pre-commit install. Once installed, every time you commit, pre-commit will run the configured hooks against changed files.

Flutter client#

Add the FLET_VIEW_PATH and FLET_WEB_PATH variables to the environment variables or profile scripts for your respective OS, making sure to modify the path accordingly:

  • On macOS (in ~/.zprofile or any other profile script)*: 

    # Flet
export FLET_VIEW_PATH="$HOME/{path-to-flet}/flet/client/build/macos/Build/Products/Release"
export FLET_WEB_PATH="$HOME/{path-to-flet}/flet/client/build/web"

  • On Windows (open "System Properties" > "Environment Variables", then add a new environment variable):

  • as "Variable name", enter FLET_VIEW_PATH, and as "Value", {path-to-flet}\flet\client\build\windows\x64\runner\Release

  • as "Variable name", enter FLET_WEB_PATH, and as "Value", {path-to-flet}\flet\client\build\web

  • On Linux (in ~/.bash_profile or any other profile script)*: 

    # Flet
export FLET_VIEW_PATH="$HOME/{path-to-flet}/flet/client/build/linux/{arch}/release/bundle"
export FLET_WEB_PATH="$HOME/{path-to-flet}/flet/client/build/web"

If you have Microsoft Edge installed and want to use it for debugging Flutter apps:

# Flutter
export CHROME_EXECUTABLE="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"

If you added these through the terminal, close that terminal session and create a new one.

* if continuing in the same shell run source ~/.zprofile to activate variables in current session

Building the Flutter client#

Open an instance of your IDE (preferably VS Code) at the flet-dev/flet/client directory.

First, run printenv | grep FLET (or gci env:* | findstr FLET on Windows) in the built-in terminal to make sure everything is set. You should see the above environment variables you set (FLET_VIEW_PATH, FLET_WEB_PATH) printed out.

  • To build the Flutter client for MacOS, run: 
    flutter build macos
    When the build is complete, you should see the Flet bundle in the FLET_VIEW_PATH. (Running it will open a blank window.)
  • To build the Flutter client for Web, run the below command: 
    flutter build web
    When the build is complete, a directory client/build/web will be created.

Running the Flutter client#

Now open another instance of VS Code at flet-dev/flet/sdk/python directory.

Create a new folder preferably named playground (it has been added to the gitignore) in which you will test your additions.

Try running the below command, where <your-main.py> is the file to test your additions:

uv run flet run -w -p 8550 playground/<your-main.py>
You should see http://127.0.0.1:8550/ opened in the browser and also a desktop window with the output of your code. Making changes to the <your-main.py> will automatically trigger a hot reload.

Now, switch to your flutter vscode instance and run the below command to start/connect the flet client: 

flutter run
then choose your device from the shown options. You will be able to see the debugging outputs of the flet client in this terminal.

Restarting/Rebuilding#

  • When you make changes to the flet dart files, you will need to restart/rerun the Flutter client for the changes to take effect in your playground. There are two ways to do this:
  • fastest: press the keyboard button R while in the client's terminal (press h to see all other possible options);

  • slowest: use flutter run as seen previously.

  • When you make changes to the flet python files, you will need to restart/rerun the Python client for the changes to take effect in the opened flutter applications. This is done with the same command:

uv run flet run -w -p 8550 playground/<your-main.py>

Releasing Flet#

  • Create a new prepare-{version} branch in flet-dev/flet repository.
  • For every package in packages/flet* directory:
  • Update package version to {version} in pubspec.yaml.
  • Add # {version} with new/changed/fixed items into CHANGELOG.md. Only packages/flet/CHANGELOG.md should contain real items; other packages could have just a stub.
  • Copy # {version} section from packages/flet/CHANGELOG.md to the root CHANGELOG.md.
  • Open terminal in client directory and run flutter pub get to update Flet dependency versions in client/pubspec.lock.
  • Create a new {version} branch in flet-dev/flet-app-templates repository from a previously released {current-version} branch.
  • Create a new {version} branch in flet-dev/flet-build-template repository from a previously released {current-version} branch.
  • Create Prepare Flet {version} PR to merge into main branch.
  • In Build Flet package for Flutter job of Flet CI build make sure analysis report of every flet* Flutter package has only 1 issue "Publishable packages can't have 'path' dependencies.".
  • Merge Prepare Flet {version} PR.
  • Create and push new v{version} tag (with v prefix).
  • Update release notes at https://github.com/flet-dev/flet/releases/tag/v{version}.

New macOS environment for Flet developer#

After installing homebrew, install xz libraries with it: 

brew install xz

Setup your shell environment: https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zprofile

Ensure Python version is 3.12.6 and location is /Users/{user}/.pyenv/shims/python:

python --version
which python

Ensure Ruby version is 3.3.5 and location is /Users/{user}/.rbenv/shims/ruby:

ruby --version
which ruby

After installing uv, set PATH: 

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.zprofile

Check uv version and make sure it's in PATH:

uv --version

Set PATH: 

echo 'export PATH=$HOME/fvm/default/bin:$PATH' >> ~/.zprofile