bpy 并非普通 pypi 包，而是 blender 内置的 python api 模块，无法通过 pip 直接安装；必须在 blender 启动的 python 环境中运行脚本才能访问 bpy，本文详解其原理、调用方式及第三方包管理方法。
bpy 并非普通 pypi 包，而是 blender 内置的 python api 模块，无法通过 pip 直接安装；必须在 blender 启动的 python 环境中运行脚本才能访问 bpy，本文详解其原理、调用方式及第三方包管理方法。
bpy 是 Blender 的官方 Python 绑定模块，它不是独立可安装的第三方库，而是一个深度集成于 Blender 运行时环境的原生模块。这意味着：你不能像 pip install requests 那样执行 pip install bpy —— PyPI 上名为 bpy 的包（如 3.4.0 版）仅为占位或历史遗留，不提供真实功能，也不兼容任意 Python 环境。你遇到的错误：
ERROR: No matching distribution found for bpy==3.6.0
正是因为 PyPI 上根本不存在真正支持 Python 3.10 的 bpy==3.6.0 发布版本；该版本号实际对应的是 Blender 3.6.0 软件本身所携带的内置 API，而非独立分发的 Python 包。
✅ 正确使用 bpy 的唯一可靠方式是：让脚本在 Blender 自带的 Python 解释器中执行。
Blender 启动时会初始化完整的内部数据结构（场景、对象、材质等），并注入 bpy 模块到其嵌入式 Python 环境中。因此，你需要通过 Blender 命令行接口（CLI）来运行脚本：
✅ 标准调用方式（推荐）
# 后台无界面模式运行（适合服务器/CI） blender --background --python myscript.py # 若需指定 Blender 版本路径（例如你已下载 blender-3.6.0-linux-x64） ./blender-3.6.0-linux-x64/blender --background --python myscript.py
其中 myscript.py 可直接导入并使用 bpy：
# myscript.py
import bpy
print("Blender version:", bpy.app.version_string) # 输出: 3.6.0
bpy.ops.mesh.primitive_cube_add() # 创建立方体（后台模式下仍生效）
bpy.data.objects["Cube"].location.z = 5.0
bpy.ops.wm.append(filepath="//collection.blend\Collection\MyCollection", directory="//collection.blend\Collection\", filename="MyCollection")
⚠️ 关键注意事项
- 不要尝试 python myscript.py：这会启动系统/conda 的 Python，import bpy 必然失败（ModuleNotFoundError）。
- Python 版本需匹配 Blender 内置解释器：Blender 3.6.0 捆绑 Python 3.10（非你 conda 环境的 3.10），二者 ABI 不兼容，不可混用。
- PATH 中的 blender 命令必须指向目标版本：确认 which blender 和 blender --version 输出为 Blender 3.6.0。
? 在 Blender 环境中安装第三方 Python 包
若脚本还需 numpy、requests 等依赖，需使用 Blender 自带的 pip：
# 查找 Blender 内置 Python 的 pip 路径（以 blender-3.6.0-linux-x64 为例） ./blender-3.6.0-linux-x64/3.6/python/bin/python3.10 -m pip install numpy requests # 或更通用的方式（自动定位） ./blender-3.6.0-linux-x64/blender --background --python-expr "import sys; print(sys.executable)" # 输出类似：/path/to/blender-3.6.0-linux-x64/3.6/python/bin/python3.10 # 然后执行： /path/to/blender-3.6.0-linux-x64/3.6/python/bin/python3.10 -m pip install pandas
? 提示：CentOS/RHEL 用户若使用系统包管理器安装的 Blender（如 dnf install blender），部分发行版会复用系统 Python，此时可直接用 dnf install python3-numpy，包将自动对 Blender 可见。
?️ 进阶方案：将 Blender 编译为 Python 模块（实验性）
Blender 官方支持将整个应用编译为可被 import bpy 的 Python 扩展模块（详见 Blender as a Python Module）。但这需要：
- 下载 Blender 源码；
- 配置 CMake 开启 WITH_PYTHON_MODULE；
- 编译安装（耗时长，需完整构建环境）；
- 最终生成 bpy.so，供系统 Python 直接 import。
该方式适用于需要深度集成 bpy 到外部框架（如 Jupyter、FastAPI）的高级场景，但不推荐初学者采用，日常开发请坚持 blender --background --python 模式。
✅ 总结
| 场景 | 正确做法 | 错误做法 |
|---|---|---|
| 运行含 import bpy 的脚本 | blender --background --python script.py | python script.py |
| 安装第三方依赖 | 使用 Blender 自带 Python 的 pip（路径形如 blender/3.6/python/bin/python3.10 -m pip） | 在 conda 环境中 pip install |
| 版本对齐 | 使用与目标 bpy API 一致的 Blender 二进制（如 bpy 3.6.0 → 必须用 Blender 3.6.0） | 试图用 pip 安装 bpy==3.6.0 |
理解 bpy 的本质——它是 Blender 运行时的一部分，而非独立库——是解决所有相关问题的前提。放弃 pip 安装幻想，拥抱 Blender CLI 工作流，即可稳定、高效地自动化 3D 处理任务。
