Python製のAIアプリ（Stable Diffusion、Qwen、Wanなど）を「Python未導入のPCでもそのまま動くスタンドアロン実行ファイル」にしたい場合、よく使われるのが PyInstaller です。
しかし、AI系ライブラリを含むアプリでは単純にビルドしただけでは失敗することが多く、以下のような追加オプションが必要になるケースがあります。
本記事では、このオプションがなぜ必要なのかを解説します。
なぜPyInstallerだけではうまくいかないのか？
PyInstallerは通常、Pythonコードを静的解析して依存関係を収集します。
例えば以下のようなコードなら問題ありません。
この場合PyInstallerは「numpyとpandasが必要」と簡単に判断できます。
しかし近年のAIライブラリは、内部で動的importや設定ファイル読み込みを多用しており、PyInstallerが必要ファイルを見落としやすくなっています。
--hidden-import transformers が必要な理由
transformers ライブラリはモデルごとに内部モジュールを動的に読み込みます。
概念的には以下のような処理です。
このような「後から必要に応じて読み込む」仕組みは、PyInstallerの静的解析では検出しづらいため、そのままだと以下のようなエラーが出ます。
そのため、--hidden-import transformers を付けて「transformersも含めろ」と明示する必要があります。
--hidden-import diffusers が必要な理由
diffusers も同様に、Stable Diffusionのパイプライン内部で多数のコンポーネントを動的ロードします。
例：
- scheduler
- tokenizer
- VAE
- UNet
- pipeline構成クラス
これらは StableDiffusionPipeline.from_pretrained() 実行時に自動ロードされるため、PyInstallerには見えません。
結果として以下のようなエラーになります。
これを防ぐために --hidden-import diffusers を追加します。
--collect-all transformers が必要な理由
transformers はPythonコードだけではなく、多数の補助ファイルを必要とします。
例えば：
- tokenizer設定ファイル
- vocabファイル
- JSON設定
- sentencepieceモデル
- metadata
PyInstallerは通常 .py ファイル中心に集めるため、これらのデータファイルが漏れることがあります。
すると実行時に：
などが発生します。
--collect-all transformers はこれら関連ファイルを丸ごと収集してくれます。
--collect-all diffusers が必要な理由
diffusers も設定ファイルやJSONメタデータを多く含みます。
必要なものの例：
- scheduler_config.json
- pipeline_config.json
- モデル設定JSON
- 内部テンプレート
不足すると：
や
が発生します。
--collect-all requests が必要な理由
HuggingFace系ライブラリはモデルダウンロードや認証で requests を頻繁に使います。
requests は以下も内部利用しています。
- SSL証明書
- certifi
- charset_normalizer
- CA bundle
これらが欠けると：
などの通信エラーになります。
実務でおすすめのPyInstaller構成
AIアプリを安定してexe化したい場合、以下のようにPyTorchも含めるのがおすすめです。
注意点：ファイルサイズは巨大になる
この方法のデメリットとして、完成するexeサイズはかなり大きくなります。
目安：
- 軽量アプリ：数十MB
- PyTorch込み：数百MB
- Stable Diffusion全部入り：1GB超えも普通
そのため、配布時は以下の代替案も検討できます。
- ONNX Runtime化して軽量化
- Docker配布
- Nuitkaで最適化コンパイル
まとめ
Stable DiffusionやQwenなどのAIアプリをPyInstallerでスタンドアロン化する際に追加オプションが必要なのは、AIライブラリが非常に動的な設計になっているためです。
ポイントを整理すると：
| オプション | 目的 |
|---|---|
--hidden-import |
動的import漏れ防止 |
--collect-all |
設定/JSON/データファイル漏れ防止 |
requests collect |
SSL証明書/通信関連漏れ防止 |
AIアプリをexe化する場合、通常のPythonアプリよりかなり複雑になるため、このあたりを理解しておくとトラブルシュートしやすくなります。
