Nuitka 将 python 程序编译成 exe 指南

Windows平台编译exe流程

安装Nuitka

pip install nuitka
Windows环境下，编译命令

python -m nuitka --mingw64 --standalone --onefile --show-progress --follow-imports your_script.py

重要参数说明

--standalone：生成独立可执行文件，无需Python环境

--onefile：打包成单一exe文件，便于分发

--windows-console-mode=disable：隐藏控制台窗口（适合GUI程序）

--output-dir=目录名：指定输出目录

--enable-plugin=tkinter,pyqt5：启用特定GUI框架插件

--windows-icon-from-ico=图标路径.ico：设置exe图标

--mingw64参数指定使用MinGW64编译器

--standalone 参数会包含所有依赖，--onefile 会将所有内容打包成单个 exe 文件

注意:

如果python程序涉及到网页界面的，上面命令不会自动包含templates和static等静态文件目录，导致运行时无法找到index.html模板文件

需要通过使用--include-data-dir参数显式包含templates目录下的index.html模板。

python -m nuitka --mingw64 --standalone --onefile --show-progress --follow-imports --include-data-dir=templates=templates your_script.py

如果还有static目录（CSS/JS/图片等），也需要一并包含：

python -m nuitka --mingw64 --standalone --onefile --show-progress --follow-imports --include-data-dir=templates=templates --include-data-dir=static=static your_script.py

目录结构：

your_project/

├── app.py

├── templates/

│ └── index.html

└── static/ (如果有)

Windows平台安装wsl来编译.bin流程

安装wsl：

https://openx.huawei.com/wsl-auto-setup/overview
配置python版本，编译python项目

安装pyenv

curl https://pyenv.run | bash

配置~/.bashrc

echo 'export PATH="HOME/.pyenv/bin:HOME/.pyenv/bin:HOME/.pyenv/bin:PATH"' >> ~/.bashrc

echo 'eval "(pyenvinit−−path)"′>> /.bashrcecho′eval"(pyenv init --path)"' >> ~/.bashrc echo 'eval "(pyenvinit−−path)"′>> /.bashrcecho′eval"(pyenv virtualenv-init -)"' >> ~/.bashrc

source ~/.bashrc

安装Python 3.12.5

pyenv install 3.12.5

设置全局默认版本

pyenv global 3.12.0

设置当前目录版本

pyenv local 3.11.5

设置shell临时版本

pyenv shell 3.10.12

进入项目目录

cd /mnt/d/your_nuitka_project

创建并激活虚拟环境

pyenv virtualenv 3.12.5 nuitka-env

pyenv activate nuitka-env

安装Nuitka

pip install nuitka

编译项目（保留命令行参数支持）

python -m nuitka --standalone --onefile --show-progress

--follow-imports

your_script.py

如果编译后的exe运行时提示"ModuleNotFoundError"，根据错误信息添加相应的--include-package=参数即可，一般无需这个参数。

另外，python程序依赖的外部库，wsl本地需要先安装完成，后续再执行nuitka命令自动打包exe时，才能顺利打包依赖库。

测试生成的可执行文件

./your_script.bin --your-parameters

注意：

如果python程序涉及到网页界面的，

使用Nuitka将Flask应用编译成exe时，它不会自动包含templates和static等静态文件目录，导致运行时无法找到index.html模板文件

需要通过使用--include-data-dir参数显式包含templates目录下的index.html模板。

python3 -m nuitka --standalone --onefile --show-progress --follow-imports --static-libpython=yes --include-data-dir=templates=templates app.py

如果还有static目录（CSS/JS/图片等），也需要一并包含：

python3 -m nuitka --standalone --onefile --show-progress --follow-imports

--include-data-dir=templates=templates

--include-data-dir=static=static

app.py

目录结构：

your_project/

├── app.py

├── templates/

│ └── index.html

└── static/ (如果有)

Linux版本的常见报错：

运行bin时，提示Segmentation fault
内存问题导致

首先检查并升级Nuitka版本

检查当前版本

python -m nuitka --version

升级到最新版本

pip install --upgrade nuitka

然后增加栈大小限制（关键步骤）

临时增加栈大小

ulimit -s 8192 # 设置为8MB

然后重新编译

python -m nuitka --standalone --onefile --show-progress --follow-imports

--include-data-dir=templates=templates

app.py

运行bin时，提示

Ubuntu系统版本导致。这个错误表明你编译的程序需要 GLIBC 2.33 版本，但你的运行环境中没有这个版本的库。这是 Linux 系统上常见的兼容性问题，通常发生在较新系统上编译的程序在较旧系统上运行时。

建议：最安全的方法是在目标系统相同或更低版本的 Linux 系统上编译。

Linux环境下运行./main.bin时，输入配置文件需输入全路径：

bash 复制代码

例如输入：
./config/icbc_config.json

可能会遇到代理问题报错

HTTP proxy handshake with ipv4:127.0.0.1:3131 failed: UNKNOWN: HTTP proxy returned response code 504

此时禁用Linux系统代理即可解决：

复制代码

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

如果是在虚拟机运行的Linux系统上运行程序，需要注意将config文件中的网关ip地址修改为Linux系统内的ip地址。

ip addr #Linux下查看IP地址