摘要：在 UV 的开发依赖环境中使用 PyInstaller 打包 Python 项目时，需注意环境隔离、依赖处理、路径配置等问题，以下是关键注意点及解决方案：
在 UV 的开发依赖环境中使用 PyInstaller 打包 Python 项目时，需注意环境隔离、依赖处理、路径配置等问题，以下是关键注意点及解决方案：
uv treePyInstaller 需作为开发依赖安装在 UV 环境中，否则无法识别环境内的第三方库。
作为开发依赖安装（推荐，不影响生产环境）
uv add --dev pyinstaller安装后，UV 会将其记录到 pyproject.toml 和 uv.lock 中，确保团队成员环境一致。
当使用 uv add 命令安装库时，加上 --dev 参数，UV 会将该库记录到 pyproject.toml 的 “开发依赖” 配置中，而非 “运行时依赖”。
使用--dev参数的好处：
1. 环境隔离：生产环境安装依赖时，不会安装这些开发工具，减少冗余；2. 依赖清晰：通过配置文件可明确区分 “项目必须的依赖” 和 “开发辅助工具”；3. 团队协作：新成员克隆项目后，可通过命令一键安装所有开发依赖，快速搭建开发环境。以后在其他计算机上克隆本项目（包含 pyproject.toml）时，安装项目的所有开发依赖（如测试工具、代码规范工具），可运行：
安装项目的所有开发依赖
uv sync --devuv sync 是 UV 的 “同步依赖” 命令，默认仅安装 project.dependencies 中的运行时依赖；
加上 --dev 后，会同时安装 project.optional-dependencies.dev 中的所有开发依赖。
uv run pyinstaller -F convert_docx_to_md.py --name convert_docx_to_md-F 全称 --onefile，表示将所有代码、依赖库和资源文件打包成一个单独的可执行文件（而非多个文件或文件夹），便于分发和使用。
convert_docx_to_md.py 是需要被打包的 Python 源文件
--name convert_docx_to_md 指定打包后生成的可执行文件的名称为 convert_docx_to_md
若项目中使用 importlib 动态导入模块，或依赖通过非标准方式加载（如自定义路径），PyInstaller 可能无法自动检测到这些依赖，导致打包后运行报错。
解决方案：
在 pyinstaller 命令中通过 --hidden-import 手动指定隐藏依赖，例如：uv run pyinstaller -F main.py --hidden-import=module.submodule或通过 spec 文件（运行 pyinstaller 后生成的 .spec）的 hiddenimports 列表配置，批量添加需要显式声明的依赖：a = Analysis(['main.py'],hiddenimports=['module1', 'module2.sub'], # 手动添加隐藏依赖# ...其他配置)若打包出现依赖版本冲突、路径混乱等难以排查的问题，可利用 UV 的高效环境管理能力重置环境：
删除项目下 .venv目录
# 重新创建环境并安装依赖（根据 pyproject.toml 重建）
来源：小象科技观