pyinstaller コマンドの基本使い方【コマンド一覧】

以下は、PyInstaller を使って Python スクリプトからスタンドアロンの実行可能ファイルを作成する際に利用できる主要なコマンド（＝コマンドラインオプション）や、付随するユーティリティツールの一覧とその解説です。バージョンや環境により若干の違いがある場合もありますが、以下の内容は一般的な使い方および主要オプションとなります。

---

1. pyinstaller コマンドの基本使い方

PyInstaller のメインコマンドは、

pyinstaller [オプション] スクリプトファイル [その他のスクリプト...]

の形で使用します。実行すると、指定した Python スクリプトを解析して、必要なモジュールやリソースをまとめ、配布可能な実行形式（Windows の場合は .exe など）を作成します。

---

2. 主要オプション一覧と解説

2.1. 基本オプション

• -h, --help
  ヘルプメッセージを表示して終了します。
  例： pyinstaller --help

• --version
  PyInstaller のバージョン情報を表示して終了します。
  例： pyinstaller --version

• --clean
  ビルド前にキャッシュや一時ファイル（ビルドディレクトリ内のファイル）を削除します。
  → キャッシュ関連の問題がある場合に有用です。

• --noconfirm
  既存のビルド成果物（spec ファイルや出力ディレクトリ）があっても、確認なしに上書きします。

• --log-level LEVEL
  ログの詳細度を指定します。
  → DEBUG, INFO, WARN, ERROR, CRITICAL などを設定可能。
  例： pyinstaller --log-level DEBUG myscript.py

---

2.2. 出力先・作業ディレクトリの指定

• --distpath DISTPATH
  ビルド完了後の実行可能ファイルやフォルダの出力先を指定します。
  → デフォルトは ./dist
  例： pyinstaller --distpath ./output myscript.py

• --workpath WORKPATH
  ビルド時に生成される一時ファイル（中間成果物）の出力先を指定します。
  → デフォルトは ./build
  例： pyinstaller --workpath ./build_temp myscript.py

• --specpath SPECPATH
  生成される spec ファイル（ビルド設定ファイル）の保存先を指定します。
  → デフォルトはスクリプトと同じディレクトリ
  例： pyinstaller --specpath ./specfiles myscript.py

---

2.3. バンドル方法の選択

PyInstaller では、バンドル方法として「フォルダ形式」と「単一ファイル形式」の 2 通りが選べます。

• -D, --onedir
  （デフォルト）複数ファイルを含むフォルダを生成します。
  → ファイルの中身を確認・デバッグしやすい

• -F, --onefile
  すべてのファイルをひとつの実行可能ファイルにまとめます。
  → 配布が簡単ですが、起動時に一時フォルダへ展開される仕組みです。

---

2.4. アプリケーション名・アイコンの設定

• --name NAME
  出来上がる実行可能ファイル（またはフォルダ）の名前を指定します。
  → 指定しなければ、最初のスクリプトのファイル名が使用されます。

• --icon <FILE>
  アプリケーションにアイコンを追加します。
  → Windows では .ico ファイル、macOS では .icns ファイルを指定
  例： pyinstaller --icon myicon.ico myscript.py

---

2.5. 追加ファイル（データ・バイナリ）の取り込み

アプリケーション実行時に必要な追加リソースをバンドルに含める場合：

• --add-data <SRC;DEST>
  追加のデータファイルをバンドルに含めます。
  → Windows では区切りに ;、Linux/macOS では : を使用
  例（Windows）： --add-data "config/settings.json;config"
  例（Linux/macOS）： --add-data "config/settings.json:config"

• --add-binary <SRC;DEST>
  追加のバイナリファイルをバンドルに含めます。
  → 使い方は --add-data と同様

さらに、Python パッケージから自動的にリソースを収集するためのオプションも用意されています：

• --collect-data MODULE
  指定したモジュールからデータファイルを収集します。

• --collect-binaries MODULE
  指定したモジュールからバイナリファイルを収集します。

• --collect-all MODULE
  指定したモジュールのすべてのリソース（データ、バイナリ、その他）を収集します。

• --collect-submodules MODULE
  指定したモジュールのサブモジュール全体を収集します。

• --copy-metadata PACKAGE
  指定したパッケージのメタデータをコピーします。

• --recursive-copy-metadata PACKAGE
  指定したパッケージおよびその依存関係のメタデータを再帰的にコピーします。

---

2.6. モジュールのインポート制御

PyInstaller はスクリプト内のインポートを自動解析しますが、場合によっては以下のオプションで補足が必要です：

• --hidden-import MODULENAME
  自動検出されないモジュールを明示的に指定して含めます。
  → 複数回指定可能
  例： pyinstaller --hidden-import=requests.packages.urllib3 myscript.py

• --additional-hooks-dir HOOKSPATH
  独自の hook ファイルが格納されているディレクトリを追加で指定します。

• --runtime-hook RUNTIME_HOOK
  ビルドされたアプリケーション起動時に、他のコードよりも先に実行されるフックスクリプトを指定します。
  → 複数指定可能
  例： pyinstaller --runtime-hook=hooks/rhook.py myscript.py

• --paths PATH
  インポートパスに追加するディレクトリを指定します。
  → 依存モジュールの発見がうまくいかない場合に利用します。

---

2.7. デバッグ・最適化関連のオプション

• --debug [all|imports|bootloader|noarchive]
  ビルドした実行可能ファイルのデバッグ情報を有効にします。

  • all：すべてのデバッグ情報を有効にする
  • imports：インポートに関するデバッグ出力
  • bootloader：ブートローダのデバッグ出力
  • noarchive：Python コードをアーカイブせず、展開状態にする

• --strip
  バイナリからデバッグシンボルを除去して、ファイルサイズを削減します（主に Unix 系 OS）。

• --noupx
  UPX（実行可能ファイルの圧縮ツール）による圧縮を無効にします。
  → UPX 使用時に問題が発生する場合に利用

• --upx-dir UPX_DIR
  UPX の実行可能ファイルがあるディレクトリを指定します（PATH に含まれていない場合など）。

• --upx-exclude FILES
  UPX 圧縮の対象から除外するファイルを、カンマ区切りで指定します。

---

2.8. セキュリティ関連

• --key KEY
  バンドル内の Python バイトコードを暗号化するためのキーを指定します。
  → 逆コンパイル対策として利用可能ですが、あくまで難読化レベルの対策となります。

---

2.9. プラットフォーム固有のオプション

【Windows 関連】

• --win-private-assemblies
  Windows 向けにプライベートアセンブリ（必要な DLL 等）をバンドルします。

• --win-no-prefer-redirects
  Windows のシステム DLL のリダイレクト（標準版ではなく別バージョンの DLL を使う挙動）を無効にします。

【macOS 関連】

• --osx-bundle-identifier BUNDLE_IDENTIFIER
  macOS アプリケーションのバンドル識別子（例："com.example.myapp"）を設定します。

---

3. PyInstaller に付随するその他のユーティリティコマンド

PyInstaller をインストールすると、pyinstaller コマンドの他にもいくつかの補助ツールが利用可能です。

3.1. pyi-makespec

• 概要：
  Python スクリプトからビルド設定ファイル（.spec ファイル）を生成します。
  spec ファイルを生成してから編集することで、より詳細なビルド設定（追加ファイルの指定、カスタムフックの設定など）が可能になります。

• 使い方：

  pyi-makespec myscript.py
  

3.2. pyi-archive_viewer

• 概要：
  生成された実行可能ファイル内に含まれる Python アーカイブ（.pyz）の内容を表示します。
  バンドル内容の確認や、問題発生時のデバッグに役立ちます。

• 使い方：

  pyi-archive_viewer myapp.exe
  

3.3. pyi-bindepend (主に Windows)

• 概要：
  Windows 用に、実行可能ファイルの DLL などのバイナリ依存関係を解析するツールです。

• 使い方：

  pyi-bindepend myapp.exe
  

3.4. pyi-win32manifest (主に Windows)

• 概要：
  Windows アプリケーション用のマニフェストファイルを生成・管理するためのツールです。
  アプリケーションの互換性や管理者権限などを指定する際に利用します。

• 使い方：

  pyi-win32manifest myapp.exe
  

---

4. まとめ

PyInstaller は、豊富なオプションにより、シンプルなスクリプトから複雑なアプリケーションまで柔軟にスタンドアロン化できるツールです。
主要なコマンドやオプションを整理すると、以下のような流れになります：

1. 基本のビルド
   → pyinstaller myscript.py
   （デフォルトでは one-folder モードでビルド）

2. 単一ファイルでのビルド
   → pyinstaller -F myscript.py

3. アイコン追加や名前指定などのカスタマイズ
   → pyinstaller -F --name MyApp --icon myicon.ico myscript.py

4. 追加ファイルや隠しインポートの指定
   → pyinstaller -F --add-data "data/file.dat;data" --hidden-import moduleX myscript.py

5. 詳細な設定が必要な場合は spec ファイルを生成して編集
   → pyi-makespec myscript.py で spec ファイル作成後、pyinstaller myscript.spec でビルド

また、バンドル後の内容確認や依存関係の調査には、pyi-archive_viewer や pyi-bindepend などの補助ツールを活用してください。

より詳細な情報や最新のオプションについては、公式ドキュメント の参照をおすすめします。

---

このように、PyInstaller では多数のオプションを利用して、さまざまな要件に合わせたビルドが可能です。用途に合わせて必要なオプションを選択・組み合わせることで、効率的なアプリケーションの配布が実現できます。