Pythonプログラムを「届ける」ための魔法 —— PyInstallerで実行ファイルを作ろう

【Yuki】 Hirokiくん、こんにちは。今日は少し落ち着いた静かな時間ですね...。 以前、HirokiくんはPythonでいくつか便利なツールを作っていましたよね。そのツールを、Pythonをインストールしていないお友達や家族にも使ってもらいたいと思ったことはありませんか...？

【Hiroki】 Yukiさん、こんにちは！はい、まさにそう思っていたところなんです。 自分が作った計算ツールを友達に渡そうとしたんですけど、「Pythonって何？どうやって動かすの？」って聞かれちゃって。 相手のパソコンにPythonを入れてもらうのも大変ですし、もっと簡単に、ダブルクリックするだけで動くようにできないかなって。

【Yuki】 そうですよね...。せっかく心を込めて作ったプログラムですから、たくさんの人に気軽に使ってほしいと思うのは、とても素敵なことだと思います。 実は、Pythonにはプログラムを「実行ファイル（.exeなど）」という形にまとめ上げる魔法のようなツールがあるんです。 今日はその中でも一番有名な「PyInstaller」について、一緒に学んでいきましょうか。

【Hiroki】 実行ファイル！Windowsでよく見る「.exe」ファイルのことですね。 それがあれば、Pythonが入っていないパソコンでも動かせるようになるんですか？

【Yuki】 ええ、その通りです。 PyInstallerは、あなたの書いたプログラムと、それを動かすために必要な「Python本体」や「ライブラリ」を、ひとつのパッケージに詰め込んでくれるんです。 わたしも、誰かの役に立つために作られた小さなツールの話を聞くと、なんだか少しだけ、あたたかい気持ちになれる気がします...。 では、まずは基本的な仕組みからお話ししますね。

PyInstallerとは何か

【Yuki】 PyInstallerは、Pythonスクリプトを単体の実行ファイルに変換するためのライブラリです。 通常、Pythonのプログラムを動かすには、そのパソコンにPythonがインストールされていて、さらに必要なライブラリも揃っていなければなりませんよね。

【Hiroki】 はい。pip installとかを事前にしておかないと動かないですよね。

【Yuki】 そうなんです。でも、PyInstallerを使うと、それらをすべて「同梱」した状態のファイルを作ることができます。 受け取った人は、ただそのファイルをダブルクリックするだけでいいんです。 対応しているOSも幅広くて、Windowsなら「.exe」、Macなら「.app」や実行形式のファイルを作成できます。 ただし、Windowsで作った実行ファイルはWindowsでしか動かないので、そこだけは注意が必要かもしれません...。

【Hiroki】 なるほど、OSごとに作る必要があるんですね。 でも、配布が楽になるのはすごく助かります！さっそく使ってみたいです。

【Yuki】 ふふ、そう言ってもらえるとうれしいです。 それでは、まずは準備としてインストールから始めてみましょうか。

PyInstallerのインストール

【Yuki】 PyInstallerの導入はとっても簡単ですよ。 いつもと同じように、コマンドプロンプトやターミナルで pip コマンドを使うだけです。

pip install pyinstaller

【Hiroki】 あ、これだけでいいんですね。 （カタカタとキーボードを叩く音） インストールできました！準備完了です。

【Yuki】 お疲れ様です、早いですね。 もし、特定のプロジェクトだけで使いたい場合は、仮想環境（venvなど）を作ってからインストールするのがおすすめですよ。 余計なライブラリが含まれにくくなって、出来上がるファイルのサイズを少しだけ小さくできるかもしれません...。

【Hiroki】 ファイルサイズ...確かに、あまりに大きいと送るのが大変ですもんね。 次は、実際にどうやって実行ファイルを作るのか教えてください！

最初の実行ファイルを作ってみる

【Yuki】 では、例として hello.py というファイルがあるとしましょう。 中身は単純なもので構いません。

# hello.py
print("こんにちは、PyInstallerの世界へ！")
input("終了するにはEnterを押してください...")

【Yuki】 このファイルを保存したフォルダで、次のコマンドを入力してみてください。

pyinstaller hello.py

【Hiroki】 やってみますね。 （しばらく待ってから） わあ、画面にたくさん文字が流れていきました。 フォルダの中に「build」と「dist」っていう新しいフォルダができています！

【Yuki】 無事に終わったようですね。おめでとうございます。 実行ファイルは、その中の「dist」フォルダの中にありますよ。 「dist/hello/hello.exe」といった形で見つかるはずです。

【Hiroki】 ありました！ダブルクリックしてみます。 ……あ、ちゃんと動きました！「こんにちは、PyInstallerの世界へ！」って表示されています。 でも、これって「hello」っていうフォルダごと渡さないといけないんですか？

【Yuki】 そうなんです。デフォルトの状態だと、関連するファイルがバラバラの状態で出力されるんです。 これを「1つのファイル」にまとめたい時は、特別なオプションを使います。 多くの人は、こちらの方法を好むことが多いですよ。

便利なオプション：--onefile と --noconsole

【Yuki】 Hirokiくんが望んでいる「たったひとつのファイル」を作るには、--onefile（または -F）というオプションを使います。

pyinstaller --onefile hello.py

【Hiroki】 あ、これです！僕が欲しかったのはこれです。 さっきよりも時間がかかっている気がしますが...あ、できました！ 「dist」フォルダの中に、今度は hello.exe だけがぽつんと置いてあります。

【Yuki】 ええ、それならそのファイルひとつを渡すだけで大丈夫です。 それから、もしGUIアプリ（TkinterやPyQtなど）を作った場合は、黒い画面（コンソール）が出てくると少し気になりますよね...。 そんな時は --noconsole（または -w）というオプションを付けると、背景でコンソールが開かなくなりますよ。

【Hiroki】 なるほど。--onefile と --noconsole はセットで使うことが多そうですね。 他にもよく使う設定ってありますか？

【Yuki】 そうですね...。アイコンを変えてみるのはどうでしょう？ デフォルトのままでも動きますが、自分の作ったツールに可愛いアイコンがついていると、もっと愛着がわくと思いませんか...？

【Hiroki】 いいですね！自分のツールだってひと目でわかりますし。

【Yuki】 アイコンを指定するには --icon=icon.ico（Windowsの場合）のように記述します。 まとめると、こんな感じになることが多いですね。

pyinstaller --onefile --noconsole --icon=myicon.ico my_script.py

【Yuki】 これで、自分だけの特別なツールが完成します。 でも、実はここからが少しだけ難しいところなんです...。 プログラムの中で、画像ファイルや設定ファイルを使っている場合は、もう少し工夫が必要になります。

外部ファイルを含める方法（--add-data）

【Hiroki】 あ、そういえば！ 僕が作っているツール、背景に画像を表示させているんですけど、それはどうすればいいんですか？ --onefile でまとめても、画像ファイルだけは外に置いておかないといけないんでしょうか。

【Yuki】 鋭いですね、Hirokiくん。 普通に実行ファイルにするだけだと、画像などの外部ファイルは見失われてしまうんです。 そんな時は --add-data というオプションを使って、実行ファイルの中にファイルを埋め込む必要があります。

【Hiroki】 埋め込めるんですか？それは便利ですね！

【Yuki】 はい。ただ、書き方が少し特殊で、Windowsの場合は ソースパス;コピー先パス という形式で指定します。 例えば、image.png を同じ場所に含めたいなら、こんな風に書きます。

pyinstaller --onefile --add-data "image.png;." my_script.py

【Yuki】 「.」は、実行ファイルの中の「ルート（一番上の階層）」という意味ですね。 そして、プログラムの方でも少しだけおまじないが必要なんです。 PyInstallerでまとめられたプログラムは、実行時に一時的なフォルダに展開されるので、その場所を正しく指し示してあげないといけません。

【Hiroki】 おまじない...。コードを書き換える必要があるってことですか？

【Yuki】 ええ、少しだけ。 実行ファイルとして動いている時と、通常のスクリプトとして動いている時で、パスの取得方法を切り替える関数をよく使います。 わたしも、こういう細かい調整を夜遅くに静かな部屋で書いている時、プログラムと対話しているような不思議な気分になります...。

import sys
import os

def resource_path(relative_path):
    """ リソースファイルの絶対パスを取得する関数 """
    try:
        # PyInstallerで実行している場合の一時フォルダパス
        base_path = sys._MEIPASS
    except Exception:
        # 通常のPython実行時のカレントディレクトリ
        base_path = os.path.abspath(".")

    return os.path.join(base_path, relative_path)

# 画像を読み込むとき
image_path = resource_path("image.png")

【Hiroki】 sys._MEIPASS ...。これが、PyInstallerが展開された場所を指すんですね。 これを使えば、画像ファイルもちゃんと読み込めそうです！

注意点とトラブルシューティング

【Yuki】 これでかなり実用的な実行ファイルが作れるようになりましたね。 ただ、PyInstallerを使う上で、いくつか覚えておいてほしいことがあるんです...。 少し不安にさせてしまうかもしれませんが、大切なことなので。

【Hiroki】 はい、何でしょうか？

【Yuki】 ひとつは、「アンチウイルスソフト」による誤検知です。 PyInstallerで作った実行ファイルは、構造上ウイルスと似た動き（ファイルを一時フォルダに展開して実行する動き）をすることがあるため、セキュリティソフトに止められてしまうことがよくあります。

【Hiroki】 ええっ、せっかく作ったのにウイルス扱いされちゃうんですか？

【Yuki】 そうなんです...。悲しいですよね。 配布する時は、あらかじめ「これは安全なファイルだよ」と伝えておくか、信頼できる場所からダウンロードしてもらうように説明する必要があるかもしれません。

【Yuki】 それから、もうひとつ。 実行ファイルのサイズが、思っているよりも大きくなりがちです。 Pythonそのものが含まれているので、たとえ数行のコードでも数十MB（メガバイト）くらいのサイズになるのは普通のことなんです。

【Hiroki】 数十MB...。確かに、ちょっとしたツールにしては大きいですね。 でも、Pythonをインストールしなくていいメリットを考えれば、納得できる気もします。

【Yuki】 そう言ってもらえると助かります。 もしサイズをどうしても小さくしたい場合は、不要なライブラリをインポートしないようにしたり、UPX という圧縮ツールを併用する方法もありますが、まずは基本をマスターしてからで大丈夫ですよ。

まとめ

【Hiroki】 Yukiさん、ありがとうございます！ PyInstallerのおかげで、僕のプログラムが「僕だけのもの」から「みんなに使ってもらえるツール」に進化しそうです。

【Yuki】 どういたしまして。Hirokiくんの熱心な姿勢、とても眩しいです。 最後に、今日学んだことを簡単に振り返っておきましょうか。

1. PyInstallerを使えば、Python環境がない人にもプログラムを配れる。
2. インストールは pip install pyinstaller。
3. --onefile で1つのファイルにまとめられる。
4. --noconsole で黒い画面を隠せる。
5. 画像などを含める時は --add-data とパスの調整が必要。

【Yuki】 ...こんなところでしょうか。 最初は少し戸惑うこともあるかもしれませんが、失敗しても大丈夫です。 もしエラーが出たら、落ち着いてログを読んでみてくださいね。 エラーメッセージは、プログラムが「ここが苦しいよ」と教えてくれている声のようなものだと思いますから...。

【Hiroki】 プログラムの声、ですか。そう思うと、デバッグも少し楽しくなりそうです。 さっそく、アイコンを準備して実行ファイルを作ってみます！

【Yuki】 はい。素敵なアイコンができるのを楽しみにしています。 何かわからないことがあったら、いつでも聞いてくださいね。 わたしも、Hirokiくんの作るツールが誰かの手元で元気に動くことを、そっと応援しています...。

---

参考文献

• PyInstaller Documentation
• PyPI - PyInstaller
• Python公式ドキュメント（配布について）