この記事では、Nuitkaを使ってPythonコードを実行ファイル化する基本手順をまとめます。
Windows 11 + PowerShell + Python仮想環境を前提に、最小構成から実務でよく使うオプションまで整理します。
Nuitkaとは
Nuitkaは、PythonコードをC/C++経由でコンパイルし、実行ファイル化できるPythonコンパイラです。
Nuitkaは単なる「exe化ツール」というより、Pythonコードを解析し、C/C++のビルド工程を経由して実行ファイルを生成するコンパイラ寄りのツールです。
読み方は日本語圏では 「ヌイトカ」 が一般的です。
この記事の前提環境
OS : Windows 11
Shell : PowerShell
Python : Python 3.12系
環境管理 : uv / venv
Compiler: Visual Studio 2022 Build Tools など
Nuitkaと仮想環境の関係
Nuitkaを理解するときは、以下のように分けて考えると分かりやすいです。
Pythonコード
↓
仮想環境 .venv
├─ Python本体
├─ Nuitka本体
└─ アプリの依存ライブラリ
↓
Nuitka
↓
SCons / Cビルド工程
↓
MSVC / MinGW / Clang などのCコンパイラ
↓
.exe / .dist / onefile
仮想環境が管理するのは、主にPython側の依存関係です。
一方、Nuitkaのビルドでは以下のようなPython外の要素も関係します。
- Cコンパイラ
- Windows SDK
- リンカ
- DLL探索
- データファイル同梱
- 一時ビルドディレクトリ
そのため、.venv が正常でも、Cコンパイラ側に問題があるとNuitkaビルドは失敗します。
PythonパッケージのビルダーとNuitkaのビルダーは別物
ここは混乱しやすいポイントです。
Pythonパッケージ側のビルダー
pyproject.toml に書かれるようなビルダーです。
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
これは、Pythonパッケージをwheel化したり、editable installしたりするためのビルダーです。
Nuitka側のビルダー
Nuitka側では、Pythonコードを解析した後、Cコンパイラを使って実行ファイルを生成します。
Nuitka
↓
SCons
↓
C compiler
↓
実行ファイル
つまり、同じ「ビルド」という言葉でも、以下は別物です。
| 種類 | 目的 |
|---|---|
pyproject.toml の build-backend |
Pythonパッケージを作る |
| Nuitka / SCons / Cコンパイラ | 実行ファイルを作る |
uv run を使うと、Nuitkaを起動する前に pyproject.toml 側の処理が走る場合があります。
そのため、Nuitkaの初期検証では .venv を有効化してから python -m nuitka を直接実行する方が切り分けしやすいです。
Nuitkaをインストールする
pipなら・・・
python -m pip install nuitka
uvなら・・・
Nuitkaをインストールします。
uv pip install nuitka
インストール確認方法
python -m nuitka --version
Nuitkaは nuitka main.py のように直接実行するより、python -m nuitka main.py と実行する方が安全です。
どのPython環境のNuitkaを使っているかが明確になるためです。
最小構成でビルドする
まずは、最小構成のPythonファイルを作成します。
# main.py
def main():
print("Hello Nuitka")
input("終了するには Enter キーを押してください...")
if __name__ == "__main__":
main()
通常のPythonとして実行します。
python main.py
問題なく動作したら、Nuitkaでビルドします。
python -m nuitka main.py
生成された実行ファイルを実行します。
.\main.exe
Nuitkaでビルドする前に、まずPythonスクリプトとして正常に動作することを確認します。
動かないPythonコードをNuitkaでビルドしても、原因切り分けが難しくなります。
ビルドモード
Nuitkaには複数のビルドモードがあります。
| モード | コマンド例 | 用途 |
|---|---|---|
| 通常ビルド | python -m nuitka main.py |
学習・検証用 |
| standalone | python -m nuitka --mode=standalone main.py |
フォルダごと配布 |
| onefile | python -m nuitka --mode=onefile main.py |
単一exe配布 |
通常ビルド
python -m nuitka main.py
最もシンプルなビルドです。
ただし、他のPCへ配布する用途には向きません。
standaloneビルド
python -m nuitka --mode=standalone main.py
main.dist のようなフォルダが生成されます。
このフォルダ内に、実行ファイルや必要なDLLなどがまとめられます。
配布するときは、基本的に .dist フォルダごと渡します。
main.dist/
├─ main.exe
├─ python311.dll
├─ ...
onefileビルド
python -m nuitka --mode=onefile main.py
単一のexeファイルを作成します。
ただし、onefileは内部的に一時フォルダへ展開してから実行されるため、standaloneよりも原因切り分けが難しい場合があります。
まずは --mode=standalone で動作確認し、問題がなければ --mode=onefile に進むのがおすすめです。
出力先を指定する
ビルド成果物の出力先は --output-dir で指定できます。
python -m nuitka `
--mode=standalone `
--output-dir=dist `
main.py
この例では、dist フォルダにビルド成果物が出力されます。
dist/
└─ main.dist/
├─ main.exe
└─ ...
プロジェクト直下にビルド成果物が散らからないため、実務では指定しておくと管理しやすいです。
出力ファイル名を指定する
出力される実行ファイル名は --output-filename で指定できます。
python -m nuitka `
--mode=onefile `
--output-filename=my_app.exe `
main.py
この場合、my_app.exe という名前で出力されます。
前回ビルド成果物を削除する
検証中は、前回のビルド成果物が残って混乱することがあります。
その場合は --remove-output を使います。
python -m nuitka `
--mode=standalone `
--remove-output `
main.py
実務では、以下のように --output-dir とセットで使うと便利です。
python -m nuitka `
--mode=standalone `
--output-dir=dist `
--remove-output `
main.py
アイコンを設定する
Windowsアプリのアイコンは --windows-icon-from-ico で指定できます。
python -m nuitka `
--mode=onefile `
--windows-icon-from-ico=app.ico `
main.py
PNG画像を指定できる場合もあります。
python -m nuitka `
--mode=onefile `
--windows-icon-from-ico=app.png `
main.py
実務用ツールでは、アイコンを設定しておくと利用者がアプリを識別しやすくなります。
コンパイラを選択する
NuitkaはPythonコードをC/C++経由でコンパイルするため、Cコンパイラが必要です。
Windowsでは、まずVisual Studio系コンパイラを使うのが分かりやすいです。
python -m nuitka `
--mode=standalone `
--msvc=latest `
main.py
代表的なコンパイラ指定は以下です。
| オプション | 意味 |
|---|---|
--msvc=latest |
Visual Studio系コンパイラを使う |
--mingw64 |
MinGW64を使う |
--clang |
Clang系コンパイラを使う |
--zig |
Zigを使う |
Windows実務では、まず --msvc=latest を基本形にしてよいです。
Visual Studio 2022 Build Tools が入っている環境なら、この指定が分かりやすいです。
GUIアプリをビルドする
GUIアプリをビルドする
Tkinter や Flet などのGUIライブラリを使用している場合は、以下のオプションコマンドが必要となります。
| ライブラリ | オプション |
|---|---|
| Tkinter | --enable-plugin=tk-inter |
| CustomTkinter |
--enable-plugin=tk-inter / --include-package-data=customtkinter
|
| Flet | flet build windows |
GUIアプリでコンソールを出さない
GUIアプリでは、実行時に黒いコンソール画面を出したくない場合があります。
その場合は --windows-console-mode=disable を指定します。
python -m nuitka `
--mode=onefile `
--windows-console-mode=disable `
main.py
ただし、開発中はコンソールを出した方がエラーを確認しやすいです。
最初からコンソールを無効化すると、例外やエラーメッセージが見えにくくなります。
まずはコンソールありで動作確認し、完成後に --windows-console-mode=disable を付けるのがおすすめです。
並列ビルド・job数を調整する
Nuitkaのビルドでは、Cコンパイル工程でCPUやメモリを使います。
--jobs を指定すると、並列数を調整できます。
python -m nuitka `
--mode=standalone `
--jobs=4 `
main.py
メモリ不足やビルド不安定が発生する場合は、並列数を落とします。
python -m nuitka `
--mode=standalone `
--jobs=1 `
main.py
さらにメモリ使用量を抑えたい場合は、--low-memory を使います。
python -m nuitka `
--mode=standalone `
--low-memory `
main.py
データファイルを同梱する
実務アプリでは、Pythonコード以外に設定ファイル、画像、テンプレートファイルなどを使うことがあります。
例として、以下のような構成を考えます。
project/
├─ main.py
├─ config/
│ └─ settings.json
└─ assets/
└─ icon.png
単一ファイルを同梱する
python -m nuitka `
--mode=standalone `
--include-data-files=config/settings.json=config/settings.json `
main.py
ディレクトリごと同梱する
python -m nuitka `
--mode=standalone `
--include-data-dir=assets=assets `
main.py
パッケージ内データを同梱する
python -m nuitka `
--mode=standalone `
--include-package-data=some_package `
main.py
Nuitkaでよくあるエラーの1つが、データファイル不足による FileNotFoundError です。
Pythonコード以外のファイルを使う場合は、明示的に同梱指定が必要です。
ファイルパスの注意点
Nuitkaでビルドしたアプリでは、カレントディレクトリに依存した書き方は避けた方が安全です。
避けたい書き方
with open("config/settings.json", encoding="utf-8") as f:
data = f.read()
この書き方は、実行時のカレントディレクトリによって失敗する可能性があります。
推奨する書き方
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent
config_path = BASE_DIR / "config" / "settings.json"
with open(config_path, encoding="utf-8") as f:
data = f.read()
__file__ を基準にすれば、スクリプトや実行ファイル周辺のファイルを安定して参照しやすくなります。
onefileでは実行時に一時フォルダへ展開されるため、ファイルパスの扱いがstandaloneより複雑になります。
データファイルまわりで詰まった場合は、まずstandaloneで確認するのがおすすめです。
よく使うオプション一覧
| 目的 | オプション |
|---|---|
| standaloneビルド | --mode=standalone |
| onefileビルド | --mode=onefile |
| 出力先指定 | --output-dir=dist |
| 出力名指定 | --output-filename=app.exe |
| 前回成果物削除 | --remove-output |
| Visual Studioコンパイラ使用 | --msvc=latest |
| アイコン指定 | --windows-icon-from-ico=app.ico |
| GUIでコンソール非表示 | --windows-console-mode=disable |
| job数指定 | --jobs=4 |
| メモリ節約 | --low-memory |
| 単一ファイル同梱 | --include-data-files=src=dst |
| ディレクトリ同梱 | --include-data-dir=src=dst |
| パッケージデータ同梱 | --include-package-data=package |
| 前回の成果物を削除 | --remove-output |
基本テンプレート
Windowsでstandaloneビルドする場合の基本形です。
python -m nuitka `
--mode=standalone `
--msvc=latest `
--output-dir=dist `
--remove-output `
main.py
onefileにする場合は以下です。
python -m nuitka `
--mode=onefile `
--msvc=latest `
--output-dir=dist `
--remove-output `
--output-filename=my_app.exe `
main.py
GUIアプリでコンソールを出さない場合は以下です。
python -m nuitka `
--mode=onefile `
--msvc=latest `
--output-dir=dist `
--remove-output `
--output-filename=my_app.exe `
--windows-console-mode=disable `
--windows-icon-from-ico=app.ico `
main.py
トラブルシュート
Cコンパイラが見つからない
エラー例：
Error, cannot locate suitable C compiler.
対策：
python -m nuitka `
--mode=standalone `
--msvc=latest `
main.py
Visual Studio Installerで以下が入っているか確認します。
- Desktop development with C++
- MSVC
- Windows SDK
uv run でNuitka前に失敗する
uv run は便利ですが、プロジェクト内で実行すると pyproject.toml を読んで環境更新やeditable installを行うことがあります。
そのため、Nuitkaの問題ではなく、Nuitkaを起動する前のPythonパッケージビルドで失敗する場合があります。
初期検証では、以下のように実行する方が切り分けしやすいです。
.venv\Scripts\activate
python -m nuitka --version
python -m nuitka --mode=standalone --msvc=latest main.py
onefileで動かない
まずstandaloneに戻して確認します。
python -m nuitka `
--mode=standalone `
main.py
onefileは一時フォルダへの展開が絡むため、ファイルパスやデータファイルの問題が見えにくくなります。
データファイルが見つからない
エラー例：
FileNotFoundError: [Errno 2] No such file or directory
確認すること：
-
--include-data-filesを指定しているか -
--include-data-dirを指定しているか - カレントディレクトリ依存のコードになっていないか
-
Path(__file__).resolve().parentを基準にしているか
ビルドが重い・メモリ不足になる
job数を減らします。
python -m nuitka `
--mode=standalone `
--jobs=1 `
main.py
または、低メモリモードを使います。
python -m nuitka `
--mode=standalone `
--low-memory `
main.py
学習順序のおすすめ
Nuitkaを学び直すなら、以下の順番がおすすめです。
| 順番 | 内容 | ゴール |
|---|---|---|
| 1 | 最小構成 |
main.py をビルドできる |
| 2 | standalone | フォルダ配布の形を理解する |
| 3 | onefile | 単一exeの特徴を理解する |
| 4 | 出力先・ファイル名 | ビルド成果物を整理できる |
| 5 | コンパイラ指定 |
--msvc=latest を理解する |
| 6 | GUI設定 | コンソール非表示を理解する |
| 7 | データファイル同梱 | 設定ファイルや画像を含められる |
| 8 | 実務アプリ適用 | 自作ツールを配布できる |
まとめ
Nuitkaを使うと、Pythonコードを実行ファイル化できます。
ただし、Nuitkaは仮想環境だけで完結するツールではありません。
Nuitkaでは、以下を分けて考えることが重要です。
Pythonの依存関係 → .venv が管理する
Pythonパッケージビルド → pyproject.toml / build-backend が関係する
実行ファイル化 → Nuitka / SCons / Cコンパイラ が関係する
最初は、以下の形を基本にすると切り分けしやすいです。
.venv\Scripts\activate
python -m nuitka --version
python -m nuitka --mode=standalone --msvc=latest main.py
慣れてきたら、出力先、ファイル名、アイコン、GUI設定、データファイル同梱などを追加していくのがおすすめです。