如何搭建项目并通过Poetry配置非系统全局安装的旧版Python环境

• 出现虚拟环境绑定错误Python版本、依赖装错位置的核心原因有两个：
  • poetry env use 的模糊版本匹配逻辑不可靠：仅传入3.8.9作为参数时，poetry会直接在系统PATH中搜索同名的Python可执行文件，找不到匹配结果时会自动选用PATH顺位最靠前的系统Python版本（也就是你碰到的预装3.9.4），不会主动识别pyenv给当前目录绑定的Python版本。
  • 操作顺序错位：你把eval "$(pyenv init -)"放在执行poetry shell之后才运行，意味着poetry从创建虚拟环境、识别Python路径的全流程中，根本没有加载pyenv的shim路径，自然找不到你本地通过pyenv安装的3.8.9版本。

1. 优先初始化pyenv环境并绑定项目Python版本

   mkdir myproj
   cd myproj
   
   # 先完成pyenv初始化，再执行所有后续版本指定操作
   eval "$(pyenv init -)"
   pyenv install 3.8.9
   pyenv local 3.8.9
   

2. 获取当前绑定Python的绝对路径，避免poetry版本匹配偏差

   # 获取pyenv绑定的3.8.9的python可执行文件绝对路径
   PYTHON_38_PATH=$(pyenv which python)
   # 校验路径输出，确保指向pyenv安装目录下的3.8.9版本，而非系统路径
   echo $PYTHON_38_PATH
   

3. 为poetry指定正确的虚拟环境Python绑定

   poetry init --no-interaction --python="3.8.9"
   # 传入绝对路径绑定，不要仅传入版本号参数
   poetry env use $PYTHON_38_PATH
   # 校验绑定结果
   poetry run python --version
   

4. 后续操作匹配预期逻辑

   # 依赖会安装到绑定3.8.9的虚拟环境中
   poetry add numpy
   # 自动进入绑定正确Python版本的虚拟环境
   poetry shell
   # 直接运行测试脚本即可，无需重复执行pyenv初始化
   python main.py
   

• 若之前已错误创建了绑定系统3.9.4的虚拟环境，需先删除旧环境再重新绑定：

  # 查看当前项目关联的所有虚拟环境
  poetry env list
  # 移除绑定错误版本的旧环境
  poetry env remove <对应错误环境的ID>
  

• 绑定完成后可通过poetry env info查看详细配置，确认Executable字段指向的是你指定的3.8.9路径后，再开始安装依赖，避免包安装位置错位。
• 不要在poetry流程启动后再执行pyenv初始化，pyenv的shim拦截机制必须在poetry调用Python的全流程前完成PATH注入，否则会持续出现版本错配问题。

内容的提问来源于stack exchange，提问作者Mateen Ulhaq