1. はじめに：cx_Freezeとは何か
Pythonで作成したプログラムを、Pythonがインストールされていない環境でも手軽に配布・実行できたら便利だと思いませんか？cx_Freezeは、PythonスクリプトをWindowsやMac、Linux用のスタンドアロン実行ファイル（exeやappなど）に変換できるクロスプラットフォーム対応のツールです。コマンドラインやセットアップスクリプトで簡単に使え、DLLや必要なライブラリも自動でまとめてくれます。デスクトップアプリやツールの配布に最適な選択肢です。
# hello.py
print("Hello, cx_Freeze!")
2. cx_Freezeのインストール方法
cx_Freezeはpipで簡単にインストールできます。仮想環境を作成してからインストールすると、依存関係の管理や動作確認がしやすくなります。インストール後はcxfreezeコマンドやsetup.pyスクリプトが利用可能になります。
python -m venv venv
source venv/bin/activate # Windowsの場合は .\venv\Scripts\activate
pip install cx_Freeze
3. 最もシンプルな実行ファイル生成
最も基本的な使い方は、コマンドラインから直接Pythonファイルを指定して実行ファイルを生成する方法です。cxfreezeコマンドを使い、--target-dirで出力先ディレクトリを指定します。
cxfreeze -c hello.py --target-dir dist
このコマンドで、distフォルダ内にhello.exe（Windows）やhello（Linux/Mac）が生成されます。
4. setup.pyによるカスタムビルド
複雑な設定や複数ファイル対応にはsetup.pyスクリプトを使います。cx_Freeze.setup()とExecutableを組み合わせて、アプリ名やバージョン、説明なども自由に指定できます。
# setup.py
from cx_Freeze import setup, Executable
setup(
name = "HelloCxFreeze",
version = "0.1",
description = "My cx_Freeze script",
executables = [Executable("hello.py")]
)
ビルドは次のコマンドで行います。
python setup.py build
5. GUIアプリケーションの変換
TkinterやPyQt、PySideなどのGUIアプリもcx_Freezeで実行ファイル化できます。GUIアプリの場合は、base="Win32GUI"を指定することでコンソールウィンドウを表示せずに実行できます。
# gui_app.py
import tkinter as tk
root = tk.Tk()
root.title("cx_Freeze GUI Example")
label = tk.Label(root, text="Hello, cx_Freeze GUI!")
label.pack()
root.mainloop()
# setup.py
from cx_Freeze import setup, Executable
setup(
name = "CxFreezeGUI",
version = "0.1",
description = "My cx_Freeze GUI app",
executables = [Executable("gui_app.py", base="Win32GUI")]
)
6. setup.cfgによる設定管理
Python 3.8以降では、setup.cfgファイルでビルド設定を記述できます。複数のオプションや依存モジュールの除外、パッケージの追加などを一元管理できます。
[metadata]
name = guifoo
version = 0.1
description = My GUI application!
[build_exe]
excludes = tkinter,unittest
zip_include_packages = encodings,PySide6,shiboken6
7. 複数の実行ファイルを同時に生成
setup.pyのexecutablesリストに複数のExecutableを追加することで、複数のPythonスクリプトを同時に実行ファイル化できます。
from cx_Freeze import setup, Executable
executables = [
Executable("main.py"),
Executable("tool.py")
]
setup(
name = "MultiApp",
version = "0.2",
description = "Multiple executables example",
executables = executables
)
8. 依存モジュールやデータファイルの追加
cx_Freezeはimport文から自動で依存モジュールを検出しますが、動的インポートやデータファイルはオプションで明示的に追加可能です。include_filesやincludes、excludesを活用しましょう。
build_exe_options = {
"includes": ["os", "json"],
"include_files": ["config.json", "data/"],
"excludes": ["tkinter"]
}
setup(
name = "DataApp",
version = "0.1",
options = {"build_exe": build_exe_options},
executables = [Executable("data_app.py")]
)
9. アイコンやショートカットの設定
Windowsでは、実行ファイルにアイコンを埋め込んだり、インストーラ生成時にショートカットを作成したりできます。iconやshortcutNameなどのオプションを利用します。
Executable(
"main.py",
base="Win32GUI",
icon="app.ico",
target_name="MyApp.exe"
)
10. MSIインストーラやMac用dmgの作成
cx_Freezeはbdist_msi（Windows）やbdist_dmg（Mac）でインストーラの自動生成も可能です。配布やインストールを簡単にしたい場合に便利です。
python setup.py bdist_msi
11. マルチプラットフォーム対応
cx_FreezeはWindows、macOS、Linuxなど主要OSに対応しています。ただし、各OSごとにビルド作業が必要です。例えばWindows用exeはWindows上で、Mac用appはMac上でビルドします。
# Linuxでビルド
python setup.py build
# Windowsでビルド
python setup.py build
12. トラブルシューティングとFAQ
依存ファイルの検出漏れや動的インポート、multiprocessing利用時のfreeze_support忘れなど、よくあるトラブルはFAQやドキュメントで解決策が紹介されています。必要に応じてincludesやinclude_filesを明示的に指定しましょう。
# multiprocessing利用時の例
from multiprocessing import Process, freeze_support
def f():
print("Hello from cx_Freeze")
if __name__ == "__main__":
freeze_support()
Process(target=f).start()
13. まとめと今後の展望
cx_Freezeは、Pythonプログラムを簡単に実行ファイル化できる強力なツールです。小規模なツールからGUIアプリ、業務用アプリの配布まで幅広く活用できます。ファイルサイズや起動速度も優れており、PyInstallerなど他のツールと比較しても十分なメリットがあります。今後もPython 3.13以降への対応や新しいプラットフォームへの拡張が進むことが期待されます。Pythonアプリの配布や実行ファイル化に興味がある方は、ぜひcx_Freezeを活用してみてください。