使用pyenv搭配Python 3.10.6时出现ModuleNotFoundError（Python 3.9.13无此问题）

遇到过类似的pyenv + 自定义开发模块的环境问题，结合你的情况，大概率和开发模式安装的entry-point生成或者pyenv环境隔离的细节有关，下面给你一步步的排查和解决方向：

1. 先确认pip与当前pyenv环境的绑定关系 #

有时候系统pip或者其他pyenv版本的pip会偷偷干扰安装，先确保你用的是3.10.6环境专属的pip：

# 检查当前pip所属的Python版本路径
pyenv which pip
# 正常输出应该是：<你的pyenv路径>/.pyenv/versions/3.10.6/bin/pip

如果输出不对，先重新切换环境并刷新shell：

pyenv shell 3.10.6
exec "$SHELL"

之后再重新执行pip install -e ~/code/runbook。

2. 清理开发安装的残留文件 #

开发模式（-e）安装的egg-info文件，在Python版本切换时可能会出现缓存或兼容性问题，先清理干净再重装：

# 进入runbook代码目录
cd ~/code/runbook
# 删除自动生成的egg-info目录（如果存在）
rm -rf runbook.egg-info
# 彻底卸载已安装的runbook残留
pip uninstall -y runbook
# 重新执行开发模式安装
pip install -e .

3. 验证entry-point是否正确生成 #

runbook作为控制台脚本，是通过entry-point机制注册的，检查3.10.6环境下的注册信息是否正常：

# 查看runbook的entry-point配置
pip show -f runbook | grep -A 10 "Entry-points"
# 或者直接查看egg-info里的配置文件
cat <你的pyenv路径>/.pyenv/versions/3.10.6/lib/python3.10/site-packages/runbook.egg-info/entry_points.txt

正常情况下，你应该看到类似这样的内容：

[console_scripts]
runbook = runbook.main:main

如果没有这个条目，说明你的setup.py或setup.cfg里的console_scripts配置可能有问题，或者Python 3.10对配置文件的解析逻辑有变化，需要检查配置文件里的脚本定义是否正确。

4. 绕过entry-point直接测试模块导入 #

如果直接运行runbook -h失败，先试试用Python模块的方式运行，确认模块本身是否能被正常导入：

python -m runbook -h

如果这个命令能正常工作，说明问题出在entry-point的生成或pyenv的shims脚本上，此时可以强制重新生成entry-points：

python -m pip install --force-reinstall -e ~/code/runbook

5. 检查Python 3.10的兼容性细节 #

Python 3.10对导入系统做了一些小调整，比如importlib.metadata的行为变化，检查你的runbook代码：

• 确保需要的目录下存在__init__.py（Python 3.3+支持namespace包，但开发模式下有时候需要显式的初始化文件）
• 检查代码中是否有相对导入的错误，Python 3.10对相对导入的检查更严格

6. 刷新pyenv的shims缓存 #

偶尔pyenv的shims脚本会出现缓存失效，导致命令指向错误的环境，执行刷新：

pyenv rehash

这个命令会重新生成所有pyenv管理的脚本链接，确保runbook命令指向正确的3.10.6环境。

内容的提问来源于stack exchange，提问作者Brett Stottlemyer