安装

Flet 是一个 Python 库加上一组命令行工具 —— flet create、flet run、flet build、flet test。你需要安装什么，取决于所使用的包管理器：使用 uv 时，什么都不用装。

前提条件

Python 版本

Flet 需要 Python 3.10 或更高版本。用 python --version 检查你当前的版本。

操作系统

macOS

Flet 支持 macOS 12 (Monterey) 或更高版本。

Windows

Flet 支持 64 位的 Microsoft Windows 10 和 Windows 11。

Linux

Flet 支持 Debian 10、11、12 以及 Ubuntu 20.04、22.04、24.04 LTS。

桌面端 flavor（音频与视频支持）

在 Linux 上，Flet 桌面客户端提供两种 flavor：full 与 light。

light flavor（Linux 上的默认）不包含音频与视频扩展，因此下载体积更小。full flavor 则开箱即用地内置了音频与视频支持。

要选择 flavor，可以设置 FLET_DESKTOP_FLAVOR 环境变量：

export FLET_DESKTOP_FLAVOR=full

或将其加入项目的 pyproject.toml：

[tool.flet]
desktop_flavor = "full"

如果你使用 light flavor 且需要音频或视频，则需要自行安装所需的库 —— 参见 Audio 与 Video 的配置指南。

Windows Subsystem for Linux (WSL)

Flet 应用可以在 WSL 2（Windows Subsystem for Linux 2）上运行。

但如果你遇到 cannot open display 错误，请参考这份指南进行排查。

配置包管理器

使用 uv

uv 是「一个由 Rust 编写的极速 Python 包与项目管理器」。如果你还没安装，请先安装它：

# macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

这是你唯一需要安装的东西 —— 没有单独安装 Flet 的步骤，也不需要手动创建或激活虚拟环境：

• uvx 在一个临时、一次性的环境中运行 Flet CLI，用脚手架生成一个新应用所需的一切都在其中。
• 一旦应用存在，uv run 就会从生成的 pyproject.toml 安装其依赖到该项目自己的虚拟环境中。

检查是否可用：

uvx --with flet-cli flet doctor

--with flet-cli 这部分是必需的：flet 包提供 flet 这个命令，但命令的实现本身位于独立的 flet-cli 包中。

可选：一个全局的 flet 命令

如果你更愿意输入 flet 而不是 uvx --with flet-cli flet，可以把 CLI 作为常驻的 uv 工具 安装：

uv tool install --with flet-cli flet
flet doctor

用 uv tool upgrade flet 升级它，用 uv tool uninstall flet 移除它。

这对于那些从项目外部作用于项目的命令（例如 flet create）很方便。要运行或构建应用，优先在项目内部使用 uv run flet ...，这样应用使用的是它自己固定的依赖，而不是全局依赖。

使用 pip

pip 没有等价于 uvx 的东西，因此 Flet 必须被安装进一个由你自行创建并激活的虚拟环境。

为你的应用创建一个目录，并在其中创建一个虚拟环境：

mkdir my-app
cd my-app
python -m venv .venv  # (1)!
source .venv/bin/activate  # (2)!

1. 在 Linux 和 macOS 上，如果 python 指向 Python 2.x 或不在你的 PATH 中，请使用 python3 -m venv .venv。
2. 在 Windows 上，请改用 .venv\Scripts\activate。

然后安装 Flet 并检查是否可用：

pip install 'flet[all]'
flet doctor

本文档中的每个 flet 命令都假设你已激活此虚拟环境。在新的终端会话中，你需要再次激活它。

安装了哪些内容

flet[all] 是构成一个完整 Flet 安装的那四个包的简写：

包	作用
flet	你 import flet as ft 所用的库，以及 flet 命令本身。
flet-cli	flet create、run、build、test 以及其他 CLI 命令 的实现。
flet-desktop	flet run 用来打开你应用的桌面客户端。
flet-web	flet run --web 与 flet serve 背后的 web 客户端与服务器。

当你不需要全部四个时，可以通过单独的 extra 安装它们：flet[cli]、flet[desktop]、flet[web]，或用于集成测试依赖的 flet[test]。单独的 flet 只提供库本身，这通常正是一个已部署应用所需要的。

INFO

如果你运行某个 flet 命令，而当前环境中缺少 flet-cli，Flet 会在继续之前为你安装匹配的版本。首次以桌面或 web 应用运行时，flet-desktop 和 flet-web 也会发生同样的情况。

将 Flet 加入已有项目

如果你已经有一个项目，只是想在其中加入 Flet：

使用 uv

uv add flet
uv add --dev flet-cli flet-desktop flet-web 'flet[test]'

第一条命令把 flet 作为应用的运行时依赖。第二条把工具链放进 dev 依赖组，因此它可用于 uv run flet ... 而不会随应用一起发布。这正是 flet create 所生成的布局。

使用 pip

pip install 'flet[all]'

与 uv add 不同，pip 不会记录任何东西：请自行把 flet 加入你的 requirements.txt 或 pyproject.toml。

安装预发布版本

Flet 在每次稳定版发布之前，会把预发布（"dev"）构建发布到 PyPI，这样你可以尽早试用即将到来的变更。它们列在发布历史页面上。无论是 uv 还是 pip，都不会主动安装预发布版本，除非你明确要求。

使用 uv

给任意 uv 命令加上 --prerelease allow：

# 用最新的预发布版本脚手架生成一个应用
uvx --prerelease allow --with flet-cli flet create my-app

# 或固定某个确切版本
uvx --prerelease allow --from 'flet[cli]==1.1.0.dev5' flet create my-app

# 全局 CLI，或已有项目
uv tool install --prerelease allow --with flet-cli flet
uv add flet --prerelease allow

由预发布 CLI 脚手架生成的应用，依赖的是 Flet 的预发布版本，因此运行它时同样需要该标志：

cd my-app
uv run --prerelease allow flet run

要免去反复加该标志，可在应用的 pyproject.toml 中设置一次：

[tool.uv]
prerelease = "allow"

使用 pip

传入 --pre，或固定某个确切版本：

pip install --pre 'flet[all]'

# 或
pip install 'flet[all]==1.1.0.dev5'

升级 Flet

使用 uv

# 应用自身的依赖
uv add flet --upgrade

# 全局 CLI（如果你安装过）
uv tool upgrade flet

uvx 无需升级 —— 它会自行获取新版本。如果看起来用到了过期的缓存版本，可加上 --refresh。

使用 pip

pip install 'flet[all]' --upgrade

下一步

现在你已经准备好创建你的第一个 Flet 应用了。