PythonプログラムをPyInstallerでEXE化する方法

PyInstallerとは？

PyInstallerは、Pythonで作成したプログラムを実行可能な形式（EXEファイル）に変換するためのツールです。特に複数のPythonファイルやライブラリを含むプロジェクトを一つの実行ファイルにまとめることができるため、配布時に非常に便利です。

他のEXE化ツールとの比較

ツール	複数ファイル対応	動作するOS	クロスコンパイル
PyInstaller	◎	Windows / macOS / Linux	×（各OSでビルドが必要）
cx_Freeze	○	Windows / macOS / Linux	×
py2exe	△	Windowsのみ	×

「動作するOS」と「クロスコンパイル」は別の話である点に注意してください。PyInstaller自体は3つのOSで動きますが、あるOS上で別のOS向けの実行ファイルを作ることはできません。この点は後述します。

インストールと環境設定

基本インストール

pip install pyinstaller

# インストール確認
pyinstaller --version

プロジェクトごとに仮想環境を分けておくと、EXEに不要なライブラリが巻き込まれるのを防げます。仮想環境の作り方は「VSCode + Git Bash + venvを使用したPython開発環境の構築」で解説しています。パッケージ管理にuvやPoetryを使っている場合も考え方は同じです。

クロスコンパイルはできない

PyInstallerを使ううえで最初に押さえておくべき制約が、クロスコンパイルに対応していないことです。Windows用のEXEファイルを作るには、Windows上でビルドする必要があります。macOSやLinuxでPyInstallerを実行して得られるのは、それぞれmacOS用・Linux用の実行ファイルであって、EXEファイルではありません。

公式ドキュメントでも、複数のOS向けに配布する場合は各OSにPyInstallerをインストールして個別にビルドするよう明記されています。複数OS向けに配布したい場合は、次のいずれかの方法を取ります。

対象OSの実機を使う: もっとも確実です。
仮想マシンを使う: VirtualBox、VMware、ParallelsなどでWindowsを動かし、その中でビルドします。
CIサービスを使う: GitHub Actionsのwindows-latestランナーのように、OSごとのランナーでビルドする方法です。手元にWindows機が無くてもEXEを生成できます。

なお、Linuxコンテナ上のDockerでビルドしてもWindows用のEXEは作れません。Dockerが有効なのは「Linux向けの実行ファイルを、再現性のある環境で安定して作る」という用途です。詳しくは後述します。

PyInstallerを使った基本的なEXE化手順

単一ファイルのEXE化

PyInstallerを使ってPythonスクリプトをEXE化するための基本的な手順は非常にシンプルです。以下のコマンドを実行するだけで、PythonファイルをEXEファイルに変換できます。

pyinstaller --onefile script.py

--onefileオプションを使用することで、必要なすべてのファイルを1つのEXEファイルにまとめることができます。このオプションがない場合、複数のファイルに分割された形で出力されます。

複数ファイルや依存関係を含むEXE化

PyInstallerは、外部ライブラリや画像・データファイルなど、スクリプトが依存するファイルも自動的に検出してパッケージ化します。もし特定のファイルを手動で追加する必要がある場合は、--add-dataオプションを使うことで対応可能です。

pyinstaller --onefile --add-data "data.json:." script.py

このコマンドは、data.jsonというファイルをEXE化されたプログラムと一緒にパッケージ化します。値はコピー元:コピー先の形式で、コピー先はアプリケーションのトップレベルからの相対パスです。

ここで注意したいのが区切り文字です。現在の公式ドキュメントはコロン（:）区切りで統一されています。Windows向けの解説ではセミコロン（;）を使った例が多く出回っており、Windowsでは今も動作しますが、その書き方をmacOSやLinuxでそのまま実行すると失敗します。環境を選ばないコロン形式で書いておくのが無難です。

EXE化したファイルのカスタマイズ方法

アイコンやリソースファイルの追加

EXE化したファイルにカスタムアイコンを設定するには、--iconオプションを使用します。例えば、myicon.icoというアイコンファイルを追加するには以下のようにします。

pyinstaller --onefile --icon=myicon.ico script.py

コンソールウィンドウを表示しない

GUIアプリケーションを作成する際、コンソールウィンドウを表示せずに実行したい場合は、--noconsoleオプションを使用します。

pyinstaller --onefile --noconsole script.py

これにより、実行時に黒いコンソールウィンドウが開かなくなります。GUIのウィンドウは通常どおり表示されるため、見た目のうえで不要なコンソールだけを消したい場合に使います。逆に、エラー内容を標準出力で確認したい開発中は付けないほうが調査しやすくなります。

Docker環境でのビルド（Linux向け実行ファイル）

前述のとおり、DockerでWindows用のEXEを作ることはできません。ここで紹介するのはLinux向けの実行ファイルを、再現性のある環境で安定して生成する方法です。手元の環境に入っているライブラリの影響を受けずにビルドできるため、サーバー上で動かすツールの配布に向いています。Docker自体の基本操作は「Dockerの基本」を参照してください。

Dockerでの環境構築

以下はPythonとPyInstallerを含む基本的なDockerfileです。

FROM python:3.12-slim
RUN pip install pyinstaller
WORKDIR /app
COPY . /app

ベースイメージのPythonバージョンは、サポートが継続しているものを選びます。Python 3.9は2025年10月にサポートが終了しているため、新規に作る場合は避けてください。

ビルドの実行例

上記のDockerfileを元にコンテナを構築し、その中でPyInstallerを実行します。

docker build -t pyinstaller-env .
docker run --rm -v $(pwd):/app pyinstaller-env pyinstaller --onefile script.py

それぞれのコマンドとオプションの詳細について説明します。

docker build -t pyinstaller-env .

このコマンドは、Dockerイメージを作成するために使用されます。各オプションの説明は以下の通りです。

docker build: Dockerfileをもとに新しいDockerイメージをビルド（構築）します。
-t pyinstaller-env: このオプションは、作成したDockerイメージに「pyinstaller-env」という名前（タグ）を付けます。これにより、ビルドしたイメージを後でこの名前で参照できるようになります。
.: ドット（.）は、現在のディレクトリを指定しています。このディレクトリにあるDockerfileを使用してイメージをビルドすることを意味します。

docker run --rm -v $(pwd):/app pyinstaller-env pyinstaller --onefile script.py

このコマンドは、先ほどビルドしたDockerイメージ（pyinstaller-env）を実行し、PyInstallerを使ってPythonスクリプトを実行ファイル化します。各オプションの詳細は以下の通りです。

docker run: Dockerコンテナを実行するためのコマンドです。
--rm: コンテナの実行が終了した際に、そのコンテナを自動的に削除します。これにより、不要なコンテナが残らないようになります。
-v $(pwd):/app: ホストマシンとコンテナの間でディレクトリを共有するための「ボリュームマウント」オプションです。
- $(pwd): ホストマシンの現在のディレクトリを表しています（$(pwd)は、現在のパスを取得するシェルのコマンドです）。
- /app: コンテナ内でホストの現在のディレクトリをマウントする場所です。この例では、ホストのディレクトリがコンテナ内の/appにマウントされます。
pyinstaller-env: 先ほどビルドしたDockerイメージの名前です。このイメージを使ってコンテナを実行します。
pyinstaller --onefile script.py: PyInstallerのコマンドです。Dockerコンテナ内でこのコマンドが実行され、指定したscript.pyというPythonスクリプトを1つの実行可能ファイルにまとめます。
- --onefile: PyInstallerが出力するファイルを1つにまとめるオプションです。

この方法でdist/に生成されるのはLinux用の実行ファイルです。拡張子は付きませんが、Linuxサーバー上でそのまま実行できます。Windows向けに配布したい場合は、前述のとおりWindows上でのビルドが必要です。

まとめ

PyInstallerを使うことで、Pythonプログラムを実行ファイル化し、Python環境のないコンピュータでも動かせるようになります。本記事では、インストールから基本的なEXE化の手順、アイコンやコンソール表示のカスタマイズ、そしてDockerを使ったLinux向けビルドまでを紹介しました。

最後にもう一度、いちばん間違えやすい点を挙げておきます。PyInstallerはクロスコンパイルに対応していません。Windows用のEXEが必要なら、Windows実機・仮想マシン・WindowsのCIランナーのいずれかでビルドしてください。ここを取り違えると、生成物が想定と違って配布直前に手戻りが発生します。

EXE化したプログラムは配布が容易で、特に社内ツールやクライアント向けアプリケーションで利便性を発揮します。ぜひPyInstallerを活用して、Pythonプログラムの配布をスムーズに進めてみてください。