cbuild 0.1.117

A tool like Nuitka and PyInstaller for packaging Python applications

CBuild

CBuild是一个统一的Python应用打包工具，提供了简单易用的命令行接口和配置文件支持，让你可以轻松地将Python脚本打包成可执行文件。

功能特点

• 支持PyInstaller和Nuitka两种主流打包方式
• 统一的配置文件格式，支持跨平台使用
• 自动检测和使用虚拟环境
• 智能过滤工具自身的虚拟环境
• 支持Windows、Linux和macOS平台
• 丰富的命令行参数和配置选项
• 支持单文件和目录模式打包
• 支持UPX压缩
• 支持自定义构建参数
• 自动处理版本号和元数据
• 提供详细的构建日志和错误信息
• 兼容Python 3.7及以上版本
• 支持从pyproject.toml、setup.py或Git标签自动读取版本号
• 支持Nuitka插件系统
• 更好的Windows控制台模式和UAC管理
• 改进的虚拟环境检测算法，支持多种环境管理器（venv、conda、poetry、pipenv等）

安装方式

使用pip安装

pip install cbuild

更新

pip install --upgrade cbuild

使用uv工具安装

uv tool install cbuild

更新

uv tool upgrade cbuild

快速开始

1. 初始化配置文件

在你的Python项目根目录下，运行以下命令生成默认配置文件：

cbuild

这将生成一个名为cbuild.toml的配置文件，你可以根据需要修改它。

2. 配置你的项目

编辑cbuild.toml文件，配置你的项目信息：

[general]
# 主脚本文件路径
main_script = "main.py"
# 输出目录
output_dir = "dist"
# 输出文件名
build_filename = "your-app-name"

3. 开始打包

使用Nuitka打包：

cbuild --nuitka

使用PyInstaller打包：

cbuild --pyinstaller

命令行参数

基本参数

• --nuitka, -n: 使用Nuitka打包
• --pyinstaller, -p: 使用PyInstaller打包
• --clean: 先清理输出目录
• --dry-run, -d: 仅打印将运行的命令，不实际执行
• --verbose, -v: 显示完整命令（便于调试）

配置参数

• --main-script, -m: 指定主脚本文件路径
• --output-dir, -D: 指定输出目录
• --build-filename, -f: 指定输出文件名

Windows特定参数

• --console, -c: 显示控制台窗口（Windows）
• --noconsole, -w: 隐藏控制台窗口（Windows）
• --uac, -a: 请求管理员权限（Windows）

配置文件说明

通用配置

[general]
# 主脚本文件路径
main_script = "main.py"
# 输出目录
output_dir = "dist"
# 输出文件名配置
build_filename = ""
# Python优化级别 (0-2)
optimize_level = 2
# 日志级别: DEBUG, INFO, WARNING, ERROR
log_level = "INFO"

打包配置

[packaging]
# 生成单文件可执行文件
use_single_file = true
# 移除调试符号以减小文件大小
remove_debug_symbols = true
# 自动跟随导入的模块
follow_imports = true
# 使用链接时优化
use_lto = true
# 使用UPX压缩可执行文件
use_upx = false
# 打包时排除的模块列表
exclude_modules = [
    "pyinstaller",
    "nuitka",
    "test",
    "tests",
    "__pycache__",
    "setuptools",
    "pkg_resources",
    "distutils",
    "cbuild"
]

资源配置

[resources]
# 应用图标路径（仅Windows支持.ico）
app_icon = ""
# 要添加的数据文件列表 [["src", "dst"], ...]
add_data = []
# UPX工具目录
upx_dir = "D:/upx"
# UPX压缩排除的文件
upx_exclude = ["vcruntime140.dll"]
# 显式包含的额外模块
include_modules = []

编译器配置（已弃用）

[compiler]
# 旧版编译器配置，现已迁移到[nuitka]部分
# use_clang = true
# use_latest_msvc = true

Windows系统特定配置

[windows]
# 控制台模式: true - 显示控制台, false - 隐藏控制台
console_mode = true
# 需要管理员权限
uac_admin = false
# 是否从git或pyproject.toml读取版本号并设置到编译后的程序
use_pyproject_version = false

Nuitka 特定配置

[nuitka]
# 使用Clang编译器（仅Nuitka支持）
use_clang = true
# 使用最新的MSVC编译器（仅Windows和Nuitka支持）
use_latest_msvc = true
# 启用的Nuitka插件列表
# 所有可用插件列表及描述:
# - anti-bloat: 从广泛使用的库模块源代码中移除不必要的导入(默认启用)
# - data-files: 包含由包配置文件指定的数据文件
# - delvewheel: 在独立模式下支持使用'delvewheel'的包
# - dill-compat: 支持'dill'包和'cloudpickle'兼容性
# - dll-files: 包含包配置文件指定的DLL文件
# - enum-compat: Python2和'enum'包所需
# - eventlet: 支持包含'eventlet'依赖及其对'dns'包猴子补丁的需求
# - gevent: 'gevent'包所需
# - gi: 支持GI包类型库依赖
# - glfw: 在独立模式下支持'OpenGL' (PyOpenGL)和'glfw'包
# - implicit-imports: 按照包配置文件提供包的隐式导入
# - kivy: 'kivy'包所需
# - matplotlib: 'matplotlib'模块所需
# - multiprocessing: Python的'multiprocessing'模块所需
# - no-qt: 禁用所有Qt绑定的包含
# - options-nanny: 根据包配置文件告知用户潜在问题
# - pbr-compat: 在独立模式下'pbr'包所需
# - pkg-resources: 'pkg_resources'的解决方法
# - playwright: 'playwright'包所需
# - pmw-freezer: 'Pmw'包所需
# - pyqt5: PyQt5包所需
# - pyqt6: PyQt6包在独立模式下所需
# - pyside2: PySide2包所需
# - pyside6: PySide6包在独立模式下所需
# - pywebview: 'webview'包(pywebview on PyPI)所需
# - spacy: 'spacy'包所需
# - tk-inter: Python的Tk模块所需
# - transformers: 为transformers包提供隐式导入
# - upx: 自动使用UPX压缩创建的二进制文件(单文件模式下无效)
# 示例: plugins = ["multiprocessing", "tk-inter", "pyqt5", "matplotlib", "data-files"]
plugins = []
# Nuitka自定义参数列表
# 可以添加本工具未支持的Nuitka参数
# 示例: custom_args = ["--enable-plugin=qml", "--include-plugin-directory=path/to/plugin"]
custom_args = []

PyInstaller 特定配置

[pyinstaller]
# PyInstaller自定义参数列表
custom_args = []

高级用法

使用虚拟环境

CBuild会自动检测并使用项目目录下的虚拟环境。如果项目中存在虚拟环境，CBuild会优先使用虚拟环境中的Python解释器和打包工具。

支持的虚拟环境管理器：

• venv (标准Python虚拟环境)
• conda (Anaconda/Miniconda)
• poetry
• pipenv

Nuitka插件系统

CBuild支持使用Nuitka的插件系统来增强打包功能：

[nuitka]
# 启用multiprocessing插件支持多进程
plugins = ["multiprocessing", "tk-inter", "pyqt5", "matplotlib", "data-files"]

版本号管理

您可以启用自动版本号获取功能，从项目配置或Git标签中自动读取版本：

[windows]
# 从pyproject.toml、setup.py或Git标签自动读取版本号
use_pyproject_version = true

自定义打包参数

你可以在配置文件中为Nuitka和PyInstaller添加自定义参数：

[nuitka]
custom_args = ["--enable-plugin=qml", "--include-plugin-directory=path/to/plugin"]

[pyinstaller]
custom_args = ["--console", "--noupx", "--add-binary=path/to/binary:."]

排除和包含模块

你可以在配置文件中指定要排除或包含的模块：

[packaging]
exclude_modules = ["pyinstaller", "nuitka", "test", "tests"]

[resources]
include_modules = ["requests", "beautifulsoup4"]

常见问题

1. 虚拟环境检测问题

如果CBuild未能正确检测到你的虚拟环境，你可以尝试：

• 确保虚拟环境目录位于项目根目录下
• 确保虚拟环境目录名称为.venv、venv或其他常见名称
• 检查虚拟环境中是否安装了所需的打包工具

2. 打包工具未找到

如果CBuild提示未找到打包工具，你可以：

• 在虚拟环境中安装所需的打包工具：pip install nuitka 或 pip install pyinstaller
• 确保全局环境中安装了打包工具
• 检查PATH环境变量是否包含打包工具的路径

3. 打包过程中出现错误

如果打包过程中出现错误，你可以：

• 使用--verbose参数查看详细的错误信息
• 检查主脚本文件是否存在
• 检查配置文件中的路径是否正确
• 检查依赖项是否安装完整

4. 版本号获取问题

如果版本号获取功能不能正常工作，你可以：

• 确认项目中包含pyproject.toml或setup.py文件
• 检查文件中是否包含有效的版本号配置
• 确保安装了setuptools_scm（如果是从Git标签获取版本）
• 检查Git仓库是否已初始化（如果使用Git标签版本）

5. 虚拟环境识别问题

如果CBuild未能正确识别您的虚拟环境，您可以：

• 确保虚拟环境位于项目根目录下（如.venv、venv等标准名称）
• 检查虚拟环境中是否安装了所需的打包工具
• 验证CONDA、Poetry或Pipenv环境是否正确激活

许可证

MIT License

相关项目

• Nuitka
• PyInstaller
• uv