Python 虚拟环境路径修复

Python 虚拟环境路径修复

核心结论
venv 通过 .venv\pyvenv.cfg 记录路径去「接管」外部解释器，而非复制。源 Python 路径变更后，修改 pyvenv.cfg 的 home 字段即可修复，通常无需重建。

一、问题与原理

• 现象：Python 安装目录移动 / 重命名 / 升级后，venv 找不到解释器，VSCode 调试闪退或报错
• 本质：pyvenv.cfg 只是指向外部解释器的「水管」——水电站搬走了，房子就没水没电了

二、修复：修改 pyvenv.cfg

编辑 .venv\pyvenv.cfg：

字段	说明	操作
home	解释器所在目录（PEP 405 标准字段）	必须改为新路径
executable	基础解释器完整路径（virtualenv 等写入，非标准字段）	推荐同步，非必须

home = D:\Applications\Python\Python311
executable = D:\Applications\Python\Python311\python.exe

修改完成后，通过 Python: Select Interpreter 重新选择该虚拟环境（或执行 Developer: Reload Window），以触发解释器元数据重新读取；无需重启 VSCode。

验证：虚拟环境内运行 python --version 正常输出，即修复成功。

三、注意事项

• 系统 PATH 与 pyvenv.cfg 相互独立：VSCode 扫描系统 PATH 找不到全局 Python 时弹出的「未安装」提示，与虚拟环境能否运行无关，可忽略
• 优先修复，而非重建：修改路径指向可保留全部已装包；仅当虚拟环境已无法定位或被删除、可接受牺牲既有依赖时，才重建并重装依赖
• 区分两类「变化」：
  • 基础 Python 移动（venv 原地不动）：仅改 home 即可
  • 虚拟环境本身移动：仅改 pyvenv.cfg 不够，激活脚本 activate / activate.bat / Activate.ps1 中硬编码的 VIRTUAL_ENV、Windows 下 pip.exe 头部嵌入的绝对路径也需一并更新