0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@SioComb

FletでPythonアプリをWindows向けにビルドする手順

0
Posted at

この記事では、Windows 11上でFletアプリをWindowsアプリとしてビルドする手順をまとめます。
最終的には flet build windows を実行して、配布用のWindowsアプリを作成することを目標にします。

対象読者

  • Python および Flet の基礎知識を持っている方
  • Windows向けの .exe 相当の成果物を作りたい方
  • uv または pip でPython環境を管理している方
  • Fletアプリを開発環境ではなく、配布可能なWindowsアプリとしてビルドしたい方

前提環境

項目 内容
OS Windows 11
Shell PowerShell
Python Python 3.12
パッケージ管理 uv 推奨
IDE VS Code 推奨
ビルド対象 Windowsアプリ

2026/05/20時点では、FletがPython 3.13以降に完全対応していない可能性があります。
この記事では Python 3.12 を前提に進めます。

FletのWindowsビルドで重要な考え方

FletのWindowsビルドは、単純なPythonスクリプトのexe化ではありません。

Fletは内部的にFlutterプロジェクトを生成し、FlutterのWindowsビルド機能を使ってアプリをパッケージ化します。

そのため、以下のような通常のPythonアプリとは異なる要素が関係します。

  • Flutter SDK
  • Visual StudioのC++ビルドツール
  • Windows SDK
  • CMake
  • Fletのビルドキャッシュ
  • assetsの配置
  • pyproject.tomlの設定

NuitkaやPyInstallerのような「Pythonファイルをexe化する」方式とは考え方が少し違います。

参考：

全体の流れ

大まかな流れは以下です。

1. プロジェクトフォルダを作成する
2. Python 3.12環境を用意する
3. Fletをインストールする
4. Fletアプリを作成・動作確認する
5. pyproject.tomlを整理する
6. Windowsビルドに必要な環境を確認する
7. flet doctor / flutter doctorで診断する
8. flet build windowsを実行する
9. ビルド後の成果物を確認する

💻 開発環境の構築〜テスト

1. プロジェクトフォルダを作成する

まず、アプリ用のフォルダを作成します。

mkdir my_flet_app
cd my_flet_app

既存のFletアプリがある場合は、そのプロジェクトフォルダに移動してください。

cd path\to\your\flet_app

以降の flet run や flet build windows は、基本的に pyproject.toml が存在するプロジェクトルート で実行します。
src フォルダの中などで実行すると、想定と違う挙動になることがあります。

2. uvでPython 3.12環境を作成する

この記事では uv を使う方法を主軸にします。

Python 3.12をインストールする

uv python install 3.12

プロジェクトを初期化する

uv init --python 3.12

実行後、以下のような構成になります。

my_flet_app/
├─ .python-version
├─ main.py
├─ pyproject.toml
└─ README.md

仮想環境を同期する

uv sync

uv sync を実行すると、必要に応じて .venv が作成されます。

my_flet_app/
├─ .python-version
├─ .venv/
├─ main.py
├─ pyproject.toml
├─ README.md
└─ uv.lock

Pythonのバージョンを確認します。

uv run python --version

以下のように Python 3.12.x と表示されればOKです。

Python 3.12.x

3. 仮想環境を有効化する

uv run を使う場合、必ずしも仮想環境を手動で有効化する必要はありません。

ただし、PowerShell上で明示的に仮想環境に入りたい場合は以下を実行します。

.venv\Scripts\activate

仮想環境に入ると、PowerShellの先頭に以下のような表示が出ます。

(.venv) PS C:\path\to\my_flet_app>

uv run を使う場合は、仮想環境をactivateしていなくても、プロジェクトの .venv を使ってコマンドを実行できます。

例：

uv run python --version
uv run flet --version

4. pip + venvを使う場合

uv を使わず、標準の venv と pip を使う場合は以下です。

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip

その後、Fletをインストールします。

pip install flet

pip freeze > requirements.txt で現在の環境を丸ごと固定すると、開発環境に入っている不要なライブラリまで含まれることがあります。
ビルド時のトラブルを減らすため、依存関係は pyproject.toml に必要なものだけ明示する方が安全です。

5. Fletをインストールする

まずは通常の flet をインストールします。

uv add flet

インストールできたか確認します。

uv run flet --version

flet[all] を入れると、Fletの追加機能をまとめて導入できます。

uv add "flet[all]"

ただし、flet[all] は依存関係が多く、環境によっては重くなります。
まずは flet 単体で始め、必要になったタイミングで flet[all] に切り替える方がシンプルです。

6. Fletアプリを作成する

方法A：uvプロジェクトに自分で構成を作る

この記事ではこちらを推奨します。

Fletのビルドを見据えて、以下のような構成にします。

my_flet_app/
├─ README.md
├─ pyproject.toml
├─ uv.lock
└─ src/
   ├─ main.py
   └─ assets/
      └─ icon.png

src フォルダを作成します。

mkdir src
mkdir src\assets

src/main.py を作成します。

New-Item src\main.py

シンプルなFletアプリの例です。

import flet as ft


def main(page: ft.Page):
    page.title = "My Flet App"
    page.add(ft.Text("Hello, Flet!"))


ft.app(target=main)

方法B：flet createでテンプレートを作る

Fletのテンプレートから始めたい場合は、flet create を使います。

uv run flet create my_flet_app
cd my_flet_app

uv init で作ったプロジェクトの中で、さらに flet create my_flet_app を実行すると、フォルダが二重構造になることがあります。

例：

my_project/
└─ my_flet_app/

初学者はここで実行場所を間違えやすいため、uv init で自分で構成する方法と、flet create でテンプレートを作る方法は混ぜない方が安全です。

Fletのテンプレート構成は、Fletのバージョンによって変わることがあります。
公式テンプレートを使う場合は、生成された構成に合わせて pyproject.toml やエントリーポイントを確認してください。

7. アプリを起動確認する

ビルド前に、まず通常起動できることを確認します。

必ずプロジェクトルートで実行してください。

uv run flet run

Web表示で確認したい場合は、以下です。

uv run flet run --web

flet run でエラーが出る場合、ビルド以前にアプリ本体の問題を解決する必要があります。

📝 pyproject.tomlを整理する

1. pyproject.tomlの役割

pyproject.toml には、アプリ名、Pythonバージョン、依存ライブラリ、Fletの設定などを記述します。

Fletアプリをビルドする場合、ここが整理されていないと、ビルド時に不要な依存関係を巻き込んだり、エントリーポイントが不明確になったりします。

2. pyproject.tomlの例

以下はPDF編集アプリを想定した例です。

[project]
name = "pdf-editor"
version = "0.1.0"
description = "PDF editor app built with Flet"
readme = "README.md"
requires-python = ">=3.12,<3.13"
dependencies = [
    "flet>=0.28.0",
    "pymupdf>=1.24.0",
    "pypdf>=5.0.0",
    "pillow>=10.0.0",
]

authors = [
    { name = "Your Name", email = "your.email@example.com" }
]

keywords = ["pdf", "flet", "editor"]

classifiers = [
    "Development Status :: 3 - Alpha",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Topic :: Software Development :: Libraries",
]

[project.urls]
Repository = "https://github.com/your-account/pdf-editor"
Issues = "https://github.com/your-account/pdf-editor/issues"

[tool.flet]
product = "PDF Editor"
company = "Your Company"
copyright = "Copyright (C) 2026 by Your Name"

[tool.ruff]
line-length = 80
indent-width = 4
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F"]
ignore = ["W292"]

[dependency-groups]
dev = [
    "ruff>=0.15.0",
    "black>=24.1.0",
    "mypy>=1.9.0",
    "pytest>=8.0.0",
]

[tool.uv]
package = false

3. dependenciesには必要なライブラリだけを書く

dependencies には、実行時に必要なライブラリだけを書きます。

dependencies = [
    "flet>=0.28.0",
    "pymupdf>=1.24.0",
    "pypdf>=5.0.0",
    "pillow>=10.0.0",
]

開発用のツールは dependency-groups の dev に分けます。

[dependency-groups]
dev = [
    "ruff>=0.15.0",
    "black>=24.1.0",
    "mypy>=1.9.0",
    "pytest>=8.0.0",
]

これにより、実行時に必要な依存関係と、開発時だけ必要な依存関係を分離できます。

4. [tool.uv] package = false について

[tool.uv]
package = false

これは、プロジェクトをPythonパッケージとしてインストールするのではなく、アプリケーションとして扱う設定です。

単純なFletアプリ開発で、Pythonライブラリとして配布しない場合は package = false にしておくとシンプルです。

5. [project.gui-scripts] を使う場合

プロジェクト構成によっては、以下のようにGUIエントリーポイントを定義する場合があります。

[project.gui-scripts]
pdf-editor = "gui.main:main"

ただし、これは gui/main.py に main() 関数が存在する構成を前提にしています。

例えば以下の構成です。

src/
└─ gui/
   ├─ __init__.py
   └─ main.py

この場合、gui.main:main は「gui.main モジュールの main 関数を呼び出す」という意味です。

src/main.py だけの構成であれば、gui.main:main はそのまま使えません。
自分のディレクトリ構成に合わせて変更してください。

🛠️ ビルド環境構築

1. Visual StudioのC++ビルドツールを確認する

Windows向けビルドでは、Visual StudioのC++ビルド環境が必要です。

ここで必要なのは、Visual Studio IDEそのものというより、内部で使われる以下のビルドツール群です。

  • MSVC
  • Windows SDK
  • CMake
  • C++ビルドツール

Fletアプリの開発自体は、VS Codeで十分です。
ただし、Windowsアプリとしてビルドする場合は、Visual Studio InstallerからC++ビルド環境を追加する必要があります。

Visual Studio Installerを開き、以下のワークロードを追加します。

C++ によるデスクトップ開発

英語表示の場合は以下です。

Desktop development with C++

追加で、インストールの詳細から以下を確認します。

項目 役割
C++ によるデスクトップ開発 Flet公式が要求するワークロード
C++ CMake tools for Windows Flutter/FletのWindowsビルドで使用
MSVC v143 - VS 2022 C++ x64/x86 build tools Windowsネイティブビルドに必要
Windows 10 SDK または Windows 11 SDK Windowsアプリ生成に必要

すでにVisual Studio 2022やBuild Toolsが入っている場合は、再インストールする必要はありません。
Visual Studio Installerで該当ワークロードとコンポーネントが入っているか確認してください。

2. Flutter SDKを確認する

FletのWindowsビルドでは、内部的にFlutterのビルド処理が使われます。

Flet公式ドキュメントでは、flet build の実行時に必要なFlutter SDKがPATH上に存在しない場合、初回ビルド時に自動でダウンロードされると説明されています。

そのため、最小限であれば、Flutter SDKを手動インストールしなくてもビルドできる場合があります。

ただし、以下の理由から、あらかじめFlutter SDKを確認しておくことをおすすめします。

  • flet doctor / flutter doctor で原因を切り分けしやすい
  • 社内ネットワークやプロキシ環境で自動ダウンロードに失敗することがある
  • Flutter SDKの場所やバージョンを自分で管理できる
  • Visual Studio C++ ワークロードとの連携確認がしやすい

3. Fletが要求するFlutter SDKバージョンを確認する

Fletが利用するFlutter SDKのバージョンは、以下のコマンドで確認できます。

uv run python -c "import flet.version; print(flet.version.flutter_version)"

ここで表示されたバージョンが、Fletが内部的に利用しようとするFlutter SDKのバージョンです。

4. Flutter SDKを手動でインストールする場合

Flutter SDKを手動で管理したい場合は、Flutter公式ドキュメントに従ってインストールします。

Windowsでは、主に以下の流れになります。

1. Git for Windowsをインストールする
2. Flutter SDKを任意の場所に配置する
3. Flutterのbinフォルダを環境変数PATHに追加する
4. PowerShellやVS Codeを再起動する
5. flutter doctor -vで確認する

例として、Flutter SDKを以下に配置した場合：

%USERPROFILE%\develop\flutter\

環境変数PATHには以下を追加します。

%USERPROFILE%\develop\flutter\bin

PATHを追加した後、PowerShellやVS Codeを開き直して、以下を実行します。

flutter --version
flutter doctor -v

flutter --version でFlutterのバージョンが表示されれば、PATH設定はできています。

5. flet doctorで診断する

ビルド前に、Fletの診断コマンドを実行します。

uv run flet doctor

Flutterを手動で入れている場合は、以下も確認します。

flutter doctor -v

Windows向けビルドのみを行う場合、Android toolchainやXcode関連のwarningは無視できる場合があります。
重要なのは、Windows desktop buildに必要なVisual Studio、Windows SDK、Flutter周辺が正しく認識されているかです。

🧱 ビルド

1. Windows向けにビルドする

必ず pyproject.toml が存在するプロジェクトルートで実行します。

uv run flet build windows

出力先を指定したい場合は、-o または --output を使います。

uv run flet build windows -o dist_windows

2. よく使うビルドオプション

アプリ名や会社名、バージョンを指定したい場合は以下のようにします。

uv run flet build windows `
  --project pdf_editor_app `
  --product "PDF Editor App" `
  --company "Your Company" `
  --build-version 0.1.0
オプション 内容
--project 内部的なプロジェクト名
--product アプリの表示名
--company 会社名
--build-version アプリのバージョン
-o, --output ビルド成果物の出力先
--clear-cache ビルドキャッシュを削除して再ビルド

ビルドがうまくいかない場合、キャッシュが原因のこともあるため、以下を試す価値があります。

uv run flet build windows --clear-cache

3. ビルド後の成果物を確認する

標準では、以下のような場所に成果物が出力されます。

my_flet_app/
└─ build/
   └─ windows/
      └─ ...

出力先を -o dist_windows のように指定した場合は、そのフォルダに作成されます。

確認するポイントは以下です。

  • アプリが起動するか
  • 画面が正しく表示されるか
  • 画像やアイコンが読み込めるか
  • ファイル選択や保存処理が動くか
  • PDF変換や画像処理など、重めの処理が動くか
  • 別フォルダへコピーしても動くか
  • 開発フォルダ以外でも起動するか

特にPDF編集アプリのようにファイル操作が多いアプリでは、開発時の相対パスに依存していないかを確認しておく必要があります。

✏️ 補足：PDF編集アプリで注意すること

1. 一時フォルダの扱い

ビルド後のアプリでは、開発時とカレントディレクトリが変わることがあります。

一時ファイルは、アプリフォルダ直下ではなく、OSの一時フォルダやユーザー指定の作業フォルダに出す方が安全です。

Pythonなら以下のようなライブラリが使えます。

from pathlib import Path
import tempfile

work_dir = Path(tempfile.gettempdir()) / "my_flet_app"
work_dir.mkdir(exist_ok=True)

2. assetsの扱い

アイコンや画像などは src/assets/ に置きます。

src/
├─ main.py
└─ assets/
   ├─ icon.png
   └─ sample.png

Flet側でassetsを使う場合は、パスの指定方法に注意します。

ft.Image(src="sample.png")

Pythonコード側で open("assets/sample.png") のように相対パスへ直接依存していると、ビルド後に壊れることがあります。
画像をFletのUI部品として表示する場合は、Fletのassets管理に寄せる方が安全です。

3. 外部ライブラリの依存関係

PDF処理では、以下のようなライブラリを使うことがあります。

用途 ライブラリ例
PDFを画像化 PyMuPDF, pypdfium2
画像処理 Pillow
PDF結合・分割 pypdf
Excel出力 openpyxl

これらは pyproject.toml の dependencies に明示しておきます。

⛔ よくあるエラーと対処

1. Visual Studio関連のエラー

Windows向けビルドでVisual Studio関連のエラーが出る場合は、まず以下を確認します。

Desktop development with C++

または日本語表示で、

C++ によるデスクトップ開発

がインストールされているか確認してください。

また、以下も確認します。

  • MSVC v143
  • Windows 10 SDK または Windows 11 SDK
  • C++ CMake tools for Windows

2. Developer Modeを求められる

以下のようなエラーが出る場合があります。

Building with plugins requires symlink support.
Please enable Developer Mode in your system settings.

この場合は、Windowsの開発者モードを有効化します。

PowerShellから設定画面を開く場合は以下です。

start ms-settings:developers

設定画面が開いたら、開発者モード を有効化してください。

3. 初回ビルドが遅い

初回ビルドでは、Flutter SDKや依存パッケージの取得が発生することがあります。

そのため、初回だけかなり時間がかかる場合があります。

2回目以降はキャッシュが効くため、初回より速くなることが多いです。

4. 社内ネットワークで失敗する

社内Wi-Fiやプロキシ、SSL/TLSインスペクション環境では、以下への通信で失敗することがあります。

  • PyPI
  • pub.dev
  • Flutter SDKの取得先
  • GitHub

特に uv を使っていてSSLエラーが出る場合は、環境によって以下の設定で改善することがあります。

[Environment]::SetEnvironmentVariable("UV_NATIVE_TLS", "true", "User")

ただし、会社PCの場合はセキュリティポリシーもあるため、無理に証明書検証を無効化するのは避けた方がよいです。

基本方針としては、社内CA証明書を正しく信頼させる方向で対応するのが安全です。

5. ビルド後に空ウィンドウになる

開発時の flet run では正常に動くのに、ビルド後のアプリで空ウィンドウになることがあります。

この場合は、以下を確認します。

  • main() が正しく呼ばれているか
  • ft.app(target=main) の指定が正しいか
  • 非同期初期化処理で例外が発生していないか
  • assetsのパスが壊れていないか
  • カレントディレクトリ依存のコードを書いていないか
  • 起動直後に重い処理でGUIスレッドをブロックしていないか
  • 例外が画面に出ず、裏側で落ちていないか

特に、起動直後にPDF変換やファイルスキャンなどの重い処理を同期的に実行している場合、画面が描画される前に固まることがあります。

重い処理は、画面表示後に実行するか、非同期処理・別スレッドに逃がすことを検討してください。

6. flet buildのキャッシュが原因で失敗する

設定を変えたのに挙動が変わらない場合や、過去のビルド設定が残っているように見える場合は、キャッシュ削除を試します。

uv run flet build windows --clear-cache

それでも解決しない場合は、build フォルダやFletのキャッシュを削除してから再ビルドすることも検討します。

まとめ

FletアプリをWindows向けにビルドする場合、重要なのは以下です。

  • flet build windows は単純なPython exe化ではなく、FlutterのWindowsビルドを使う
  • コマンドは pyproject.toml があるプロジェクトルートで実行する
  • uv init と flet create を混ぜると構成が分かりにくくなる
  • Visual Studio IDEではなく、C++ビルドツール群が必要
  • flet doctor と flutter doctor で原因を切り分ける
  • assetsや一時ファイルはビルド後のパスを意識する
  • 社内ネットワークではSSL/TLSやプロキシで失敗することがある
  • ビルド後の空ウィンドウは、エントリーポイント、assets、非同期処理、相対パスを疑う

開発時に動いていても、ビルド後は実行環境やカレントディレクトリ、assetsの扱いが変わることがあります。

そのため、ビルド後は必ず別フォルダへコピーして、実際の配布に近い状態で動作確認することをおすすめします。

参考リンク

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?