Pythonをexe化する方法を初心者向けに解説！PyInstallerで配布できるアプリを作ろう
Pythonで作った便利なツールを、他の人にも使ってもらいたいと思ったことはありませんか？ 自分のパソコンでは動くのに、相手のパソコンではPythonが入っていなくて動かない、という壁にぶつかる方は多いです。
そんなときに役立つのが Pythonのexe化 です。exe化すると、Pythonが入っていないWindows環境でも、ダブルクリックで実行できる形式に近づけられます。
この記事では、IT初心者の方にもわかるように、Pythonをexe化する基本をやさしく解説します。代表的なツールであるPyInstallerを使い、インストール方法、基本コマンド、よくあるエラー、配布時の注意点まで順番に見ていきましょう。
Pythonのexe化とは何か¶
Pythonのexe化とは、Pythonで書いたプログラムをWindowsの実行ファイルである.exeにまとめることです。たとえば、main.pyというファイルをmain.exeのような形に変換します。
通常、Pythonのプログラムを動かすには、実行するパソコンにPythonがインストールされている必要があります。さらに、使っているライブラリも入っていなければなりません。
しかし、exe化ツールを使うと、Python本体や必要なライブラリをまとめて、相手の環境でも実行しやすい形にできます。完全に魔法のように何でも解決するわけではありませんが、配布のハードルはかなり下がります。
初心者の方は、exe化をアプリ化の第一歩と考えるとわかりやすいです。自分だけがコマンドで実行する段階から、他の人にも渡せる形に近づける作業です。
Pythonをexe化するメリット¶
Pythonをexe化するメリットは、配布しやすくなることです。特に、Pythonに詳しくない人へツールを渡したいときに効果があります。
たとえば、業務で使うファイル整理ツールを作ったとします。自分はpython main.pyと実行できますが、同僚にそれを説明するのは少し大変です。
exe化しておけば、相手にはファイルをダブルクリックしてもらうだけで済む場合があります。これはかなり大きな違いです。
主なメリットを表にまとめると、次のようになります。
| メリット | 内容 | 初心者向けのイメージ |
|---|---|---|
| 配布しやすい | Python未インストール環境でも動かしやすい | 相手に準備してもらう作業が減る |
| 実行しやすい | ダブルクリックで起動しやすい | コマンド操作に慣れていない人にも渡しやすい |
| ライブラリをまとめられる | 必要な依存関係を同梱できる | 自分の環境に近い形で渡せる |
| ツール感が出る | .pyよりアプリらしく見える | 業務ツールとして共有しやすい |
ただし、メリットだけではありません。exe化には注意点もあります。
Pythonをexe化するときの注意点¶
exe化すると便利ですが、何でも小さくきれいにまとまるわけではありません。 特に初心者が驚きやすいのは、ファイルサイズの大きさです。
Pythonのexe化では、Pythonの実行に必要なものも一緒にまとめるため、簡単なプログラムでも数十MB以上になることがあります。helloと表示するだけなのに大きいと感じるかもしれません。
これは異常ではありません。Python本体や関連ファイルを含めているためです。
また、exe化したファイルは、作成したOSと違うOSでそのまま動くとは限りません。Windows用のexeを作るなら、基本的にはWindows環境で作ると考えておくと安全です。
私の経験では、exe化で一番大切なのは過度に期待しすぎないことです。 exe化は配布を楽にする手段ですが、すべての環境差を完全に吸収する万能ツールではありません。
Pythonのexe化によく使うPyInstallerとは¶
Pythonをexe化する代表的なツールがPyInstallerです。 Pythonのスクリプトを解析し、必要なモジュールやライブラリ、Pythonインタプリタをまとめて配布しやすい形にしてくれます。
PyInstallerはコマンド操作で使えるため、初心者でも比較的始めやすいです。まずは1つのPythonファイルをexe化するところから試すのがおすすめです。
この記事では、PyInstallerを中心に解説します。ほかにも cx_Freeze、Nuitka、py2exe などの選択肢がありますが、最初の一歩としてはPyInstallerがわかりやすいです。
代表的なツールをざっくり比較すると、次のようになります。
| ツール | 特徴 | 初心者へのおすすめ度 |
|---|---|---|
| PyInstaller | コマンドがわかりやすく、情報も多い | 高い |
| cx_Freeze | 複数OS向けの配布に使われることがある | 中くらい |
| Nuitka | PythonをC/C++経由でコンパイルする方向性 | やや上級者向け |
| py2exe | Windows向けの歴史あるツール | 用途次第 |
初心者の方は、まずPyInstallerで十分です。最初から複数ツールを比較しすぎると、手が止まりやすくなります。
exe化の前に準備するもの¶
ここから実際の手順に入ります。まずは、exe化する前に必要なものを確認しておきましょう。
必要なのは、Pythonがインストールされた環境と、exe化したいPythonファイルです。さらに、PyInstallerをインストールします。
この記事では、次のようなシンプルなファイルを例にします。
# main.py
print("こんにちは")
print("Pythonをexe化します")
このmain.pyをexe化していきます。まずはシンプルなコードで成功体験を作るのが大切です。
いきなりGUIアプリや画像ファイル付きのツールをexe化しようとすると、つまずくポイントが増えます。最初は短いコードで試しましょう。
PyInstallerをインストールする¶
PyInstallerはpipでインストールできます。コマンドプロンプトやPowerShellを開いて、次のコマンドを実行します。
pip install pyinstaller
環境によっては、python -m pip を使うほうが確実です。
python -m pip install pyinstaller
インストールできたか確認するには、次のコマンドを実行します。
pyinstaller --version
バージョン番号が表示されれば、PyInstallerを使う準備ができています。ここでエラーが出る場合は、Pythonやpipのパス設定が原因になっていることがあります。
初心者の方は、コマンドが見つからないエラーで止まりやすいです。その場合は、python -m PyInstaller のようにPython経由で実行する方法も覚えておくと安心です。
python -m PyInstaller --version
コマンド周りでつまずいたときは、焦らずにエラーメッセージを読むことが大切です。英語で表示されても、not recognizedやNo module namedのような言葉から原因を絞れます。
【関連記事】PythonのModuleNotFoundErrorって何？解決するにはどうしたらいいの？
Pythonファイルをexe化する基本コマンド¶
PyInstallerの基本はとてもシンプルです。exe化したいPythonファイルがあるフォルダで、次のコマンドを実行します。
pyinstaller main.py
python -m PyInstaller を使う場合は、次のように書きます。
python -m PyInstaller main.py
実行すると、いくつかのフォルダやファイルが作成されます。代表的なのはbuild、dist、main.specです。
それぞれの役割を表にまとめます。
| 作成されるもの | 役割 | 初心者向けの理解 |
|---|---|---|
| build | exe作成中の作業フォルダ | 基本的に触らなくてよい |
| dist | 完成した実行ファイルが入る場所 | 配布時に見るフォルダ |
| main.spec | ビルド設定ファイル | 細かく調整したいときに使う |
完成したファイルはdistフォルダの中にあります。まずは、distの中を確認して、exeファイルを実行してみましょう。
最初に成功したときは、少し感動すると思います。Pythonのコードが、アプリのような形で動くからです。
onefileで1つのexeにまとめる¶
PyInstallerでよく使うオプションが--onefileです。これを付けると、関連ファイルを1つの実行ファイルにまとめようとします。
pyinstaller --onefile main.py
実行後、distフォルダの中にmain.exeが作られます。 複数のファイルが並ぶより、1つのexeとして渡せるのでわかりやすいです。
ただし、--onefileには注意点もあります。起動時に一時フォルダへ展開するため、起動が少し遅く感じることがあります。
また、画像や設定ファイルなど外部ファイルを使うアプリでは、パスの扱いが少し難しくなることがあります。初心者のうちは、まず外部ファイルなしのシンプルなコードで--onefileを試すのがおすすめです。
コンソール画面を表示しないようにする¶
GUIアプリをexe化するとき、黒いコンソール画面が一緒に出てしまうことがあります。Tkinterなどで画面アプリを作っている場合、これは少し気になりますよね。
その場合は、--windowedまたは--noconsoleを使います。
pyinstaller --onefile --windowed app.py
または次のようにも書けます。
pyinstaller --onefile --noconsole app.py
このオプションを使うと、コンソール画面を出さずに起動できます。GUIアプリらしく見せたいときに便利です。
ただし、注意点があります。コンソールを消すと、printで出していたエラーやログが見えにくくなります。
開発中はコンソールありで動作確認し、問題がなくなってから --windowed を付けるのがおすすめです。これは実務でもよく使う進め方です。
【関連記事】PythonでGUIアプリは作れるの？TkinterやCustomTkinterで自分専用のツールを自作してみる
アイコンを付けてexe化する¶
exeファイルにアイコンを付けると、よりアプリらしく見えます。PyInstallerでは--iconオプションを使います。
pyinstaller --onefile --icon=app.ico main.py
Windows向けなら、基本的に.ico形式のアイコンファイルを用意します。png画像をそのまま指定しても期待通りにならないことがあるため、ico形式に変換しておくと安心です。
アイコンは動作そのものには関係ありません。ですが、配布するツールとして見た目を整える効果があります。
私の経験では、社内ツールでもアイコンがあるだけで使う側の印象が少し変わります。細かい部分ですが、使いやすさや安心感につながります。
画像や設定ファイルも一緒に入れる¶
Pythonアプリでは、画像、CSV、設定ファイルなどを読み込むことがあります。その場合、exe本体だけを渡しても動かないことがあります。
たとえば、config.jsonを読み込むプログラムがあるとします。
import json
with open("config.json", "r", encoding="utf-8") as file:
config = json.load(file)
print(config["app_name"])
このプログラムをexe化する場合、config.json も一緒に扱う必要があります。PyInstallerでは --add-data オプションを使います。
pyinstaller --onefile --add-data "config.json:." main.py
この例では、config.jsonを実行時のルートに追加する指定をしています。環境やPyInstallerのバージョンによって書き方の細部で迷うことがあるため、うまくいかない場合は公式ドキュメントの--add-dataの説明を確認するとよいです。
外部ファイルを扱うexe化では、パスの問題がよく起きます。今いるフォルダを基準に読むのか、exeの展開先を基準に読むのかで結果が変わるためです。
exe化後のファイルパスに注意する¶
Pythonスクリプトとして動かすときは問題なかったのに、exe化したらファイルが見つからない。これはかなりよくあるトラブルです。
原因の多くは、ファイルパスの基準が変わることです。特に--onefileでは、一時フォルダに展開されて実行されるため、単純な相対パスが期待通りに動かないことがあります。
対策として、実行時の基準パスを取得する関数を用意しておくと便利です。
import sys
from pathlib import Path
def resource_path(relative_path):
if hasattr(sys, "_MEIPASS"):
return Path(sys._MEIPASS) / relative_path
return Path(__file__).parent / relative_path
config_path = resource_path("config.json")
print(config_path)
sys._MEIPASS は、PyInstallerでonefile実行したときの一時展開先として使われることがあります。通常のPython実行時には存在しないため、hasattrで確認しています。
初心者のうちは少し難しく感じるかもしれません。ですが、画像や設定ファイルを含むexe化では、この考え方がとても重要です。
specファイルとは何か¶
PyInstallerを実行すると、main.specのようなファイルが作られます。これはexe化の設定ファイルです。
最初は触らなくても大丈夫です。基本的なexe化なら、コマンドだけで十分です。
ただし、オプションが増えてくると、毎回長いコマンドを打つのが大変になります。そのようなときにspecファイルを編集して、ビルド設定を管理できます。
たとえば、データファイルや隠れた依存関係を追加したい場合に使います。少し慣れてきたら、specファイルを見るとPyInstallerが何をしているのか理解しやすくなります。
基本的に、最初からspecファイルをいじる必要はありません。まずコマンドで成功させ、必要になったらspecファイルに進むのが挫折しにくいです。
exe化でよくあるエラーと対処法¶
ここからは、Pythonをexe化するときによくあるトラブルを見ていきます。エラーが出ても、よくある原因を知っていれば落ち着いて対応できます。
pyinstallerコマンドが見つからない¶
まず多いのが、pyinstaller と入力してもコマンドが見つからないケースです。インストールできていないか、パスが通っていない可能性があります。
その場合は、次のように実行してみてください。
python -m PyInstaller main.py
これで動くなら、PyInstaller自体は入っています。コマンド名として直接呼び出すためのパス設定がうまくいっていないだけかもしれません。
また、インストール先のPythonと実行しているPythonが違うこともあります。複数のPythonを入れている環境では特に注意が必要です。
ModuleNotFoundErrorが出る¶
exe化したあとに ModuleNotFoundError が出ることがあります。これは、必要なモジュールをPyInstallerがうまく検出できなかった場合に起こることがあります。
まずは、通常のPython実行で動くか確認しましょう。
python main.py
通常実行でもエラーが出るなら、exe化以前の問題です。必要なライブラリをpipでインストールする必要があります。
通常実行では動くのにexe化後だけエラーになる場合は、--hidden-import を試すことがあります。
pyinstaller --onefile --hidden-import=module_name main.py
module_name には、見つからないと言われているモジュール名を入れます。動的にimportしているライブラリでは、この対応が必要になることがあります。
【関連記事】Pythonの例外処理のアンチパターン5選をご紹介！｜初心者がやりがちな「べからず集」
exeがウイルス扱いされる¶
PyInstallerで作ったexeが、セキュリティソフトに警告されることがあります。これは必ずしも本当に危険という意味ではありません。
PyInstallerで作られた実行ファイルは、内部にPythonやライブラリをまとめているため、セキュリティソフトが不審に判断することがあります。特にonefile形式では起動時に一時展開するため、警告されやすい場合があります。
対策としては、配布元を明確にする、署名を検討する、社内配布ならセキュリティ担当に確認する、不要なライブラリを減らすなどがあります。
初心者が個人で配る場合でも、相手に不安を与えない説明は大切です。exeファイルは受け取る側にとって警戒されやすい形式だからです。
ファイルサイズが大きすぎる¶
簡単なPythonコードなのに、exeが数十MBから百MB近くになることがあります。これは珍しくありません。
Python本体や依存ライブラリを含めるため、ファイルサイズは大きくなりがちです。特に pandas、numpy、opencv などを使うと、サイズはさらに大きくなります。
不要なライブラリをimportしていないか確認しましょう。なんとなく便利だからと大きなライブラリを読み込むと、exeにも影響します。
実務では、サイズよりも安定して動くことを優先する場面も多いです。とはいえ、配布しやすさを考えるなら、依存関係を小さく保つ意識は大切です。
exe化する前にコードを整理しよう¶
exe化は最後の仕上げに近い作業です。コードが不安定な状態でexe化すると、原因の切り分けが難しくなります。
まずは、Pythonファイルとして普通に動くことを確認しましょう。コマンドで実行してエラーがない状態にしてからexe化するのが基本です。
python main.py
この段階で問題があるなら、先にコードを直します。exe化してからデバッグしようとすると、ログが見えにくくなり、余計に難しくなります。
また、ファイル名にも注意しましょう。日本語やスペースを含むパスでトラブルになることがあるため、最初は英数字中心のフォルダで試すと安全です。
【関連記事】Pythonのコードレビューでチェックするポイントは？
配布するときに気をつけること¶
exe化できたら、次は配布です。ここでもいくつか注意点があります。
まず、dist フォルダの中にできたものを確認しましょう。--onefile ならexeファイルだけで済むことが多いですが、外部ファイルが必要な場合はそれも一緒に渡す必要があります。
次に、別のパソコンで動作確認することが大切です。自分の環境だけで動いても、配布先で動くとは限りません。
配布前に確認したい項目を表にまとめます。
| 確認項目 | 内容 | 理由 |
|---|---|---|
| 別PCで起動するか | 自分以外の環境で試す | 環境依存を見つけるため |
| 外部ファイルが含まれているか | 設定ファイルや画像を確認 | ファイル不足を防ぐため |
| セキュリティ警告が出ないか | ウイルス対策ソフトの反応を見る | 受け取り側の不安を減らすため |
| エラー時の表示があるか | ログやメッセージを確認 | 問題発生時に対応しやすくするため |
| バージョンを管理しているか | ファイル名に日付や番号を付ける | 古いexeとの混同を防ぐため |
配布は、作ることとは別の難しさがあります。使う人の環境や不安を想像して準備することが大切です。
exe化したらソースコードは見えなくなるのか¶
exe化すると、Pythonファイルがそのまま見えなくなるため、ソースコードを完全に隠せると思うかもしれません。ですが、これは少し注意が必要です。
PyInstallerによるexe化は、基本的には配布しやすくまとめるためのものです。ソースコードを強力に保護するための仕組みではありません。
ある程度の知識がある人なら、内部の情報を解析できる可能性があります。そのため、秘密のAPIキーやパスワードをコードに直接書いてexe化するのは避けましょう。
これはとても重要です。exeにしたから安全、とは考えないほうがよいです。
実務では、秘密情報は環境変数や外部の安全な仕組みで管理します。初心者のうちから、コードに秘密情報を直接書かない習慣を持つと安心です。
GUIアプリをexe化する例¶
ここでは、Tkinterを使った簡単なGUIアプリを例にします。ボタンを押すとメッセージを表示するだけのシンプルなアプリです。
import tkinter as tk
from tkinter import messagebox
def show_message():
messagebox.showinfo("メッセージ", "こんにちは")
root = tk.Tk()
root.title("サンプルアプリ")
button = tk.Button(root, text="クリック", command=show_message)
button.pack(padx=20, pady=20)
root.mainloop()
このファイルを app.py として保存したら、次のようにexe化できます。
pyinstaller --onefile --windowed app.py
--windowedを付けることで、黒いコンソール画面を出さずにGUIアプリとして起動しやすくなります。
ただし、開発中は--windowedを外したほうがエラーを見つけやすいです。最初はコンソールありで確認し、最後に--windowedを付ける流れがおすすめです。
実務でのおすすめ手順¶
Pythonをexe化するときは、いきなり完成形を目指さないほうがうまくいきます。段階を分けて確認するのがコツです。
私が実務で意識している流れは、まずPythonスクリプトとして安定させることです。次に、外部ファイルなしの状態でexe化し、最後に画像や設定ファイルを含めます。
流れとしては、次のように進めると安全です。
まず、python main.pyで通常実行できることを確認します。次に、pyinstaller main.pyで基本のexe化を試します。
そのあと、pyinstaller --onefile main.pyで1ファイル化します。GUIなら最後に--windowedを追加します。
この順番なら、どの段階で問題が起きたのか切り分けやすいです。初心者ほど、いきなり全部のオプションを付けないほうが成功しやすいです。
まとめ¶
Pythonのexe化は、作ったツールを他の人に使ってもらうための大切なステップです。 特にWindows環境では、.exeにまとめることで配布しやすくなります。
初心者が最初に使うなら、PyInstallerがおすすめです。pipでインストールし、pyinstaller main.pyやpyinstaller --onefile main.pyのようなコマンドで試せます。
ただし、exe化には注意点もあります。ファイルサイズが大きくなる、外部ファイルのパスでつまずく、セキュリティソフトに警告される、ソースコードを完全には隠せない、といった点は理解しておきましょう。
エンジニア歴10年の私から見ると、exe化で一番大切なのは段階的に進めることです。まず通常のPython実行で動かし、次に基本のexe化、最後にonefileやwindowedなどのオプションを追加する流れが安全です。
Pythonで作ったものを誰かに使ってもらえると、学習のモチベーションも上がります。まずは短いmain.pyを用意して、PyInstallerでexe化するところから試してみてください。
ここまでお読みいただき、ありがとうございました。
