Windows 下使用 pyenv-win 管理多版本 Python：安装、配置与切换

维护与清理

pyenv update # 更新版本数据库（2.64.x/2.32.x）
pyenv rehash # 版本/库变更后重建 shims
pyenv uninstall 3.9.13 # 卸载版本
pyenv install -c # 清空下载缓存

更多命令见：主页与命令列表

四、安装'指定版本'的正确姿势

最新稳定的 3.12.x

pyenv update
pyenv latest 3.12
pyenv install 3.12.5
pyenv global 3.12.5

安装老版本并只在当前项目使用

pyenv install 3.8.10
cd D:\code\myproj
pyenv local 3.8.10

需要 32 位解释器（在 x64 机器上）

pyenv install 3.8.10-win32
pyenv local 3.8.10-win32

五、在国内如何设置 pip 源

配置 pip 国内镜像（长期有效）

清华 TUNA

python -m pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

六、常见问题与排障

• pyenv 命令找不到/版本不生效：重开终端；确认 PATH 中包含 ...\pyenv-win\bin 与 ...\pyenv-win\shims；VS Code 需重启。
• 运行 python 还是系统自带：在开始菜单关闭 Python 的应用执行别名；或检查 pyenv which python 指向是否为 ...\pyenv-win\versions\...。
• 切换版本后工具不可用：执行 pyenv rehash 以重建 shims。
• 下载慢或超时：优先配置系统代理；或使用'手动缓存安装包'的方式。
• 需要 32 位兼容：了解 32bit-train（版本号显示为 2.32.x）分支的安装与使用，见 安装指南。

七、从 0 到 1 的极速上手脚本

# 1) 安装 pyenv-win
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

# 2) 配置 pip 国内镜像（以 TUNA 为例）
python -m pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 3) 安装并切到指定版本
pyenv update
pyenv install 3.12.5 -q
pyenv global 3.12.5

# 4) 验证
pyenv version
python -c "import sys; print(sys.version, '->', sys.executable)"

参考与延伸阅读：

• 官方主页与命令列表：pyenv for Windows | pyenv-win
• 官方安装文档：Installation | pyenv-win