CMake无法找到虚拟环境中Python的调试技巧求助

问题背景 #

已激活项目目录下的Python虚拟环境（venv），此时which python指向该环境中的Python解释器，且环境已安装NumPy。使用CMake构建时执行以下命令查找Python：

find_package(Python REQUIRED COMPONENTS Interpreter Development NumPy)

但CMake未能找到该解释器，报错信息如下：

Could NOT find Python (missing: Python_EXECUTABLE Python_INCLUDE_DIRS
Python_LIBRARIES Interpreter Development NumPy Development.Module
Development.Embed)

尝试通过-DPython3_EXECUTABLE=<abs-path-to-project-root/venv/bin/python>指定路径，但仍未解决问题。

调试步骤与技巧 #

• 强制指定完整Python组件路径：不要仅指定Python3_EXECUTABLE，同时显式传入头文件和库文件路径，示例：

  cmake .. -DPython3_EXECUTABLE=/path/to/venv/bin/python3 \
           -DPython3_INCLUDE_DIR=/path/to/venv/include/python3.10 \
           -DPython3_LIBRARY=/path/to/venv/lib/python3.10/config-3.10-x86_64-linux-gnu/libpython3.10.so
  

  注意替换命令中的3.10为你虚拟环境的实际Python版本号。

• 开启CMake查找调试日志：添加--debug-find参数运行CMake，查看完整的Python搜索流程，定位具体失败环节：

  cmake .. --debug-find -DPython3_EXECUTABLE=/path/to/venv/bin/python3
  

  日志会展示CMake检查的路径、验证的文件，能帮你发现权限缺失、文件遗漏等问题。

• 检查虚拟环境完整性：确认虚拟环境包含Python开发所需的文件：

  • 查看venv/include目录下是否存在Python.h等头文件
  • 查看venv/lib或venv/lib64目录下是否存在Python共享库（.so或.dll文件）
    若缺失，先安装系统级Python开发包（如Ubuntu的python3-dev、CentOS的python3-devel），再重新创建虚拟环境。

• 手动指定NumPy路径：先在激活的虚拟环境中获取NumPy的头文件路径，再传入CMake：

  # 在激活的venv中执行，获取NumPy路径
  python -c "import numpy; print(numpy.get_include())"
  # 将输出路径传入CMake
  cmake .. -DPython3_EXECUTABLE=/path/to/venv/bin/python3 \
           -DPython3_NumPy_INCLUDE_DIR=/path/to/numpy/include
  

• 清理干扰性环境变量：运行CMake前，临时取消可能覆盖虚拟环境的系统变量：

  unset PYTHONPATH PYTHONHOME
  cmake .. -DPython3_EXECUTABLE=/path/to/venv/bin/python3
  

• 升级CMake版本：旧版本CMake对Python虚拟环境的支持存在bug，建议升级到3.18及以上版本（该版本优化了虚拟环境的查找逻辑）。

内容的提问来源于stack exchange，提问作者Dmitry Kabanov