Pyenv安装的Python通过venv创建的虚拟环境缺少include文件与python-config

核心结论 #

venv默认不会复制父环境的头文件和python-config类工具，这是设计特性而非bug。针对你的多版本Python开发场景，可通过以下几种方式解决：

1. 使用venv的--copies参数创建完整环境 #

创建虚拟环境时添加--copies参数，会直接复制父环境的二进制文件、头文件及配置脚本，而非仅使用符号链接：

python3.10 -m venv --copies my_venv

注意：此方式会增大虚拟环境体积，但能确保每个环境独立拥有完整的开发组件，避免版本混淆。

2. 改用Pyenv官方虚拟环境插件pyenv-virtualenv #

作为Pyenv的配套工具，pyenv-virtualenv会自动关联对应Python版本的开发组件，无需手动处理：

1. 安装插件（可通过Homebrew或Git克隆）
2. 创建并激活虚拟环境：

   # 基于指定Pyenv版本创建
   pyenv virtualenv 3.10.x my_venv
   # 激活环境
   pyenv activate my_venv
   

   激活后，虚拟环境会自动继承对应版本的include目录和python-config，切换Python版本时不会出现路径冲突。

3. 自动化脚本实现原生venv的补全 #

如果坚持使用原生venv，可编写shell脚本自动完成头文件链接和python-config复制修正：

#!/bin/bash
# 用法：./create_venv.sh <虚拟环境名称> <Python版本号，如3.10>
VENV_NAME=$1
PY_VERSION=$2

# 创建基础虚拟环境
python${PY_VERSION} -m venv ${VENV_NAME}

# 获取父环境的include路径并创建符号链接
PARENT_INCLUDE=$(python${PY_VERSION} -c "import sysconfig; print(sysconfig.get_path('include'))")
ln -s ${PARENT_INCLUDE} ${VENV_NAME}/include/python${PY_VERSION}

# 复制并修正python-config脚本
PARENT_CONFIG=$(which python${PY_VERSION}-config)
cp ${PARENT_CONFIG} ${VENV_NAME}/bin/
# macOS下sed需要加''参数避免报错
sed -i '' "s|$(pyenv prefix ${PY_VERSION})|$(pwd)/${VENV_NAME}|g" ${VENV_NAME}/bin/python${PY_VERSION}-config

保存为create_venv.sh并赋予执行权限，运行./create_venv.sh my_venv 3.10即可自动生成带完整开发组件的虚拟环境。

补充说明 #

venv的设计目标是隔离运行时依赖，而非构建完整开发环境，因此默认不会包含编译C扩展所需的头文件和配置工具。这种取舍适配了大多数运行场景，但针对开发需求，上述方案可在不破坏环境隔离原则的前提下解决问题。

内容的提问来源于stack exchange，提问作者Nick Williams