Nuitka 基础操作

一、Nuitka 简介

Nuitka 是一个强大的 Python 编译器，它可以将 Python 代码编译成 C 级别的可执行文件，不仅能让程序在没有 Python 环境的机器上运行，还能显著提升执行效率。与传统的打包工具（如 PyInstaller）不同，Nuitka 的核心原理是将 Python 代码转换为 C++ 代码，再通过 C 编译器编译为机器码，因此生成的程序运行速度更快。

本文将详细介绍 Nuitka 的各个参数含义和使用场景，帮助您根据项目需求灵活配置编译选项。

二、安装与环境准备

2.1 安装 Nuitka

pip install nuitka

2.2 验证安装

nuitka --version
# 或
python -m nuitka --version

注意：官方推荐使用 python -m nuitka 而不是直接运行 nuitka 命令，这样可以确保使用正确的 Python 解释器。

2.3 系统依赖

Nuitka 需要 C 编译器支持：

• Windows：Visual Studio 2017+ 或 MinGW64
• Linux：gcc 或 clang
• macOS：Xcode 命令行工具

三、参数分类详解

3.1 基础输出模式

参数	说明	使用场景
--standalone	创建包含所有依赖的独立文件夹，生成的程序可移植到其他机器	程序需要分发，且接受文件夹形式
--onefile	在 standalone 基础上，将所有文件打包为单个可执行文件	追求单文件分发，如绿色软件
--module	编译为可导入的扩展模块（.so/.pyd），而不是可执行程序	开发 C 扩展模块
--mode	编译模式：accelerated/standalone/onefile/app	统一指定编译模式

示例：

# 生成独立文件夹
nuitka --standalone script.py

# 生成单文件
nuitka --onefile script.py

注意：--onefile 已隐含 --standalone，无需重复添加。

3.2 优化相关参数

参数	说明	使用场景
--lto=yes	启用链接时优化（Link Time Optimization），减小文件体积并提升性能	生产环境发布，可接受编译时间增加
--lto=thin	启用薄 LTO，平衡优化效果和编译时间	大型项目，需要优化但不想等待太久
--lto=no	禁用 LTO（默认值）	快速测试编译
--optimize=N	优化级别，N=0/1/2，数字越大优化越多	根据需求平衡编译速度和运行效率

示例：

# 最大优化
nuitka --standalone --lto=yes --optimize=2 script.py

3.3 模块包含与控制

参数	说明	使用场景
--include-package=PACKAGE	显式包含整个包及其子模块	自动检测遗漏的包，如 --include-package=requests
--include-module=MODULE	显式包含单个模块	包含特定模块，如 --include-module=utils
--follow-imports	递归跟踪所有导入的模块（standalone 模式下默认开启）	确保所有依赖都被编译
--nofollow-imports	不跟踪任何导入模块（standalone 模式下不可用）	简单脚本，无需依赖
--follow-import-to=MODULE	仅跟踪指定模块的导入	精细化控制依赖范围
--nofollow-import-to=MODULE	忽略指定模块的导入	排除不必要的依赖，如 --nofollow-import-to=*.tests
--follow-stdlib	跟踪标准库模块的导入	需要完全自包含，但会大幅增加编译时间

示例：

# 包含特定包，排除测试模块
nuitka --standalone --include-package=myapp --nofollow-import-to=*.tests script.py

3.4 资源文件处理

参数	说明	使用场景
--include-data-dir=SRC=DEST	递归包含整个目录的数据文件	包含静态资源文件夹，如图片、配置文件
--include-data-files=SRC=DEST	包含单个或多个匹配模式的数据文件	包含特定文件，支持通配符
--include-package-data=PACKAGE	包含包内的数据文件（非代码文件）	处理包自带的数据文件
--noinclude-data-files=PATTERN	排除匹配模式的数据文件	剔除不需要的资源

示例：

# 包含图片文件夹
nuitka --standalone --include-data-dir=./images=images script.py

# 包含配置文件
nuitka --standalone --include-data-files=./config/*.yaml=config/ script.py

3.5 插件系统

参数	说明	使用场景
--enable-plugin=PLUGIN	启用指定插件	处理特殊库的依赖
--disable-plugin=PLUGIN	禁用指定插件	避免不必要的插件处理
--plugin-list	列出所有可用插件	查看插件清单

常用插件：

• tk-inter：支持 Tkinter GUI 程序
• pyside6 / pyqt5：支持 Qt GUI 程序
• numpy：支持 numpy、pandas、matplotlib
• multiprocessing：支持多进程
• torch：支持 PyTorch
• tensorflow：支持 TensorFlow
• anti-bloat：减少无用模块导入（默认自带）

示例：

# 打包 PySide6 GUI 程序
nuitka --standalone --enable-plugin=pyside6 --disable-console gui_app.py

3.6 Python 运行时标志

参数	说明	使用场景
--python-flag=FLAG	设置 Python 运行时标志	控制 Python 解释器行为
--python-debug	使用调试版 Python	调试目的（仅测试用）

常用 flag：

• -S / no_site：不导入 site 模块
• no_asserts：禁用断言（生产环境优化）
• no_warnings：禁用警告
• -O：优化模式
• no_docstrings：禁用文档字符串
• unbuffered：无缓冲输出

示例：

# 生产环境禁用断言和警告
nuitka --standalone --python-flag=no_asserts --python-flag=no_warnings script.py

3.7 输出控制

参数	说明	使用场景
--output-dir=DIR	指定编译输出目录	整理编译产物
--output-filename=NAME	指定输出文件名	自定义可执行文件名称
--remove-output	编译完成后删除中间临时文件	节省磁盘空间
--jobs=N	指定并行编译任务数，N 为负数表示系统 CPU 数减 N	加快编译速度

示例：

nuitka --standalone --output-dir=./dist --output-filename=myapp --remove-output script.py

3.8 平台特定参数

参数	说明	平台	使用场景
--disable-console	禁用控制台窗口，创建 GUI 应用程序	Windows	GUI 程序发布
--windows-icon=ICON_PATH	设置可执行文件图标	Windows	自定义图标
--windows-uac-admin	请求管理员权限	Windows	需要管理员权限的程序
--macos-create-app-bundle	创建 macOS 应用包（.app）	macOS	macOS 应用分发
--macos-app-icon=ICON_PATH	设置 macOS 应用图标	macOS	自定义图标
--linux-onefile-icon=ICON_PATH	设置 Linux 单文件图标	Linux	Linux 应用图标

示例：

# Windows GUI 程序
nuitka --standalone --onefile --disable-console --windows-icon=app.ico gui_app.py

# macOS 应用
nuitka --macos-create-app-bundle --macos-app-icon=app.icns gui_app.py

3.9 编译器选择

参数	说明	使用场景
--clang	强制使用 Clang 编译器	Linux/macOS 下使用 Clang
--mingw64	强制使用 MinGW64 编译器	Windows 下使用 MinGW
--msvc=VER	指定 MSVC 版本	Windows 下指定 Visual Studio 版本

3.10 调试与诊断

参数	说明	使用场景
--debug	启用调试模式，生成包含调试信息的可执行文件	调试编译问题
--show-scons	显示内部 SCons 构建系统的输出	查看详细编译过程
--show-progress	显示编译进度信息	监控编译进度
--show-memory	显示内存占用信息	监控内存使用
--show-modules	显示最终包含的模块列表	确认依赖完整性
--verbose	输出详细的操作信息	完整日志输出
--run	编译后立即执行生成的文件	快速测试编译结果
--debugger	在调试器中执行（如 gdb）	深入调试

示例：

# 调试编译过程
nuitka --standalone --debug --verbose --show-scons script.py

3.11 高级参数

参数	说明	使用场景
--onefile-tempdir-spec=SPEC	指定单文件解压目录模板	自定义解压路径
--onefile-no-compression	禁用单文件压缩	调试或节省编译时间
--assume-yes-for-downloads	自动确认下载依赖	CI/CD 环境
--file-reference-choice=MODE	设置 __file__ 的值：runtime/original/frozen	处理文件路径相关逻辑
--warn-implicit-exceptions	启用隐式异常警告	代码质量检查
--warn-unusual-code	启用不寻常代码警告	代码质量检查

四、实战组合示例

4.1 基础脚本编译

# 最简单的独立文件夹
python -m nuitka --standalone script.py

# 单文件版本
python -m nuitka --onefile script.py

4.2 GUI 应用程序（以 PySide6 为例）

python -m nuitka --standalone \
    --onefile \
    --disable-console \
    --enable-plugin=pyside6 \
    --windows-icon=icon.ico \
    --output-dir=./dist \
    --remove-output \
    gui_app.py

4.3 包含静态资源的 Web 应用

python -m nuitka --standalone \
    --onefile \
    --include-package=flask \
    --include-data-dir=./templates=templates \
    --include-data-dir=./static=static \
    --include-data-files=./config/*.yaml=config/ \
    --output-filename=webapp \
    app.py

4.4 数据处理项目（含 numpy/pandas）

python -m nuitka --standalone \
    --onefile \
    --enable-plugin=numpy \
    --include-package=pandas \
    --lto=yes \
    --python-flag=no_asserts \
    data_processor.py

4.5 完整生产环境配置

python -m nuitka --standalone \
    --onefile \
    --lto=yes \
    --remove-output \
    --enable-plugin=multiprocessing \
    --enable-plugin=numpy \
    --include-package=api \
    --include-package=core \
    --include-data-dir=./assets=assets \
    --include-data-files=./config/*.yaml=config/ \
    --python-flag=no_asserts \
    --python-flag=no_warnings \
    --windows-disable-console \
    --windows-icon=app.ico \
    --output-dir=./release \
    --output-filename=myapp \
    main.py

五、常见问题与解决方案

5.1 模块找不到

现象：运行时提示 ModuleNotFoundError

解决方案：

# 显式包含缺失模块
--include-package=missing_package
--include-module=missing_module

5.2 资源文件缺失

现象：运行时提示 FileNotFoundError

解决方案：

# 包含资源文件
--include-data-dir=./data=data
--include-data-files=./config.json=config.json

5.3 编译速度慢

解决方案：

# 增加并行编译
--jobs=8

# 禁用不必要的跟踪
--nofollow-import-to=*.tests

# 使用薄 LTO
--lto=thin

5.4 可执行文件过大

解决方案：

# 启用 LTO 优化
--lto=yes

# 移除调试信息
--no-debug

# 排除无用模块
--nofollow-import-to=unittest,docs,tests

5.5 查看所有可用插件

python -m nuitka --plugin-list

六、总结

Nuitka 提供了丰富而灵活的参数体系，可以满足从简单脚本到复杂应用的打包需求。掌握这些参数，您可以根据项目特点定制最优的编译策略：

需求	核心参数
基础打包	--standalone / --onefile
性能优化	--lto=yes --optimize=2
依赖控制	--include-package --nofollow-import-to
资源文件	--include-data-dir --include-data-files
特殊库支持	--enable-plugin
GUI 程序	--disable-console + 相应 GUI 插件
调试诊断	--debug --verbose --show-scons

建议先从简单的参数组合开始，逐步添加所需选项，通过 --show-modules 验证依赖完整性，最终找到最适合项目的编译配置。