Windows 下使用 pyenv-win：安装、迁移到 D 盘、配置镜像源与多版本切换实战

在 Windows 平台管理多个 Python 版本一直是一个麻烦问题：手动安装会污染 PATH，不同项目依赖不同版本时也很难切换。pyenv-win 提供了与 Linux/macOS pyenv 类似的体验，可以在同一台机器上同时安装多个 Python，并按全局/项目目录快速切换。

本文记录一次完整的 pyenv-win 安装与迁移实践，最终目标是：

pyenv-win 安装目录放在 D:\environment\pyenv-win
Python 安装包缓存不落在 C 盘
Python 各版本安装目录不落在 C 盘
pip 第三方库镜像切换为国内源
Python 安装包下载源切换为国内镜像
演示安装 Python 3.12 和 3.14，并切换到 3.12

1. pyenv-win 工作机制概述

pyenv-win 的核心目录结构如下：

bin：存放 pyenv 主命令入口（pyenv.bat 等）
shims：存放 shim 可执行文件（python/pip 等），用于动态指向当前版本
versions：存放安装的 Python 版本目录
install_cache：存放 Python 安装包下载缓存（exe 安装包）

pyenv-win 通过 shims 机制实现版本切换：

python 实际调用的是 shims\python.exe
shim 会根据当前设置（global/local/shell）跳转到 versions\<version>\python.exe

因此 PATH 的优先级非常关键。

2. 卸载旧 pyenv-win（如果之前装在 C 盘）

如果之前安装过 pyenv-win（例如默认装到了 C:\Users\<user>\.pyenv），建议彻底清理，避免 PATH 冲突。

2.1 删除旧目录

常见旧目录：

text 复制代码

C:\Users\<user>\.pyenv

可以直接删除整个 .pyenv 文件夹。

2.2 清理环境变量

进入 Windows：

系统属性 → 高级 → 环境变量

删除与旧路径相关的变量，例如：

PYENV
PYENV_HOME
PYENV_ROOT

如果存在旧的 PATH 条目，例如：

text 复制代码

C:\Users\<user>\.pyenv\pyenv-win\bin
C:\Users\<user>\.pyenv\pyenv-win\shims

也需要删除。

清理完成后建议重启一次 PowerShell 或重启系统。

3. 安装 pyenv-win 到 D:\environment\pyenv-win

pyenv-win 官方推荐 PowerShell 安装脚本，但脚本默认会安装到用户目录（C 盘）。如果希望强制安装到 D 盘，需要提前设定安装目录相关环境变量。

3.1 创建目标目录

先手动创建目录：

powershell 复制代码

mkdir D:\environment\pyenv-win

3.2 下载安装脚本（手动保存）

在 PowerShell 中执行：

powershell 复制代码

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"

这一步只是下载脚本，不执行。

3.3 设置安装路径环境变量

为了让安装脚本把 pyenv-win 安装到 D 盘，需要先设置：

powershell 复制代码

$env:PYENV="D:\environment\pyenv-win\.pyenv\pyenv-win"
$env:PYENV_HOME="D:\environment\pyenv-win\.pyenv\pyenv-win"
$env:PYENV_ROOT="D:\environment\pyenv-win\.pyenv\pyenv-win"

注意：这三条在当前 PowerShell 会话有效，如果要永久生效，需要使用 setx。

永久写入（推荐）：

powershell 复制代码

setx PYENV "D:\environment\pyenv-win\.pyenv\pyenv-win"
setx PYENV_HOME "D:\environment\pyenv-win\.pyenv\pyenv-win"
setx PYENV_ROOT "D:\environment\pyenv-win\.pyenv\pyenv-win"

执行完 setx 后必须重新打开 PowerShell 才会生效。

3.4 执行安装脚本

执行：

powershell 复制代码

&"./install-pyenv-win.ps1"

安装完成后关闭 PowerShell，重新打开。

3.5 验证安装成功

执行：

powershell 复制代码

pyenv --version

若输出类似：

text 复制代码

pyenv 3.1.1

说明安装成功。

4. 正确配置环境变量（最终可用配置）

最终环境变量配置如下（此配置已验证可用）：

4.1 环境变量

text 复制代码

PYENV
D:\environment\pyenv-win\.pyenv\pyenv-win

PYENV_HOME
D:\environment\pyenv-win\.pyenv\pyenv-win

PYENV_ROOT
D:\environment\pyenv-win\.pyenv\pyenv-win

4.2 PATH 必须包含的两项

在用户 PATH 或系统 PATH 中加入：

text 复制代码

D:\environment\pyenv-win\.pyenv\pyenv-win\bin
D:\environment\pyenv-win\.pyenv\pyenv-win\shims

并确保这两条优先级足够高，至少要排在可能存在的旧 Python 或 WindowsApps 前面。

5. 避免 WindowsApps 抢占 python 命令

Windows 10/11 默认启用了 Microsoft Store 的 Python alias，可能导致 python 命令指向 WindowsApps，而不是 pyenv 的 shim。

处理方式：

开始菜单 → Manage App Execution Aliases

关闭以下两项：

python.exe
python3.exe

这样可以避免 PATH 正确但 python 仍然被劫持的情况。

6. pyenv-win 安装 Python 后缓存与安装目录是否在 D 盘

当 pyenv-win 安装在 D 盘时，Python 安装包缓存与 Python 安装目录也会跟随落在 D 盘。

例如执行：

powershell 复制代码

pyenv install 3.12.10

输出日志会显示：

text 复制代码

:: [Downloading] ::  From https://www.python.org/ftp/python/3.12.10/python-3.12.10-amd64.exe
:: [Downloading] ::  To   D:\environment\pyenv-win\.pyenv\pyenv-win\install_cache\python-3.12.10-amd64.exe

说明缓存已经在：

text 复制代码

D:\environment\pyenv-win\.pyenv\pyenv-win\install_cache

而 Python 安装目录在：

text 复制代码

D:\environment\pyenv-win\.pyenv\pyenv-win\versions\<version>\

因此整个 Python 多版本环境可以做到完全不占用 C 盘空间。

7. 安装 Python 3.12 与 3.14，并切换到 3.12

7.1 查看可安装版本

查看完整列表：

powershell 复制代码

pyenv install -l

筛选 3.12：

powershell 复制代码

pyenv install -l | findstr 3.12

筛选 3.14：

powershell 复制代码

pyenv install -l | findstr 3.14

一般情况下：

不带后缀（如 3.12.10）表示 amd64 64位版本（推荐）
-win32 表示 32位版本（不推荐）
-arm 表示 ARM 架构版本
a/b/rc 表示测试版，不适合生产使用

7.2 安装 Python 3.12

安装最新稳定版：

powershell 复制代码

pyenv install 3.12.10

7.3 安装 Python 3.14（示例）

如果 pyenv install -l 中存在 3.14 版本，例如 3.14.0a1 或更高版本，可以安装：

powershell 复制代码

pyenv install 3.14.0a1

如果列表中出现稳定版，例如：

text 复制代码

3.14.0

则直接安装：

powershell 复制代码

pyenv install 3.14.0

7.4 查看已安装版本

powershell 复制代码

pyenv versions

7.5 切换全局版本到 3.12

powershell 复制代码

pyenv global 3.12.10

7.6 验证当前 Python 版本与路径

查看 pyenv 当前版本：

powershell 复制代码

pyenv version

验证 python 实际路径：

powershell 复制代码

python -c "import sys; print(sys.executable)"

正确输出应类似：

text 复制代码

D:\environment\pyenv-win\.pyenv\pyenv-win\versions\3.12.10\python.exe

这表示 pyenv-win 的 shim 机制完全生效。

8. 配置 Python 安装包下载镜像源（pyenv install 下载加速）

默认情况下 pyenv-win 从官方源下载 Python 安装包：

text 复制代码

https://www.python.org/ftp/python

国内网络环境下可能速度慢或不稳定，因此可以替换为国内镜像。

例如使用华为云 Python 镜像：

powershell 复制代码

setx PYTHON_BUILD_MIRROR_URL "https://mirrors.huaweicloud.com/python/"

重新打开 PowerShell 后生效。

验证：

powershell 复制代码

echo $env:PYTHON_BUILD_MIRROR_URL

之后执行 pyenv install 时，会从该镜像下载 Python 安装包。

9. 配置 PyPI 镜像源（pip install 下载加速）

Python 第三方库默认从官方 PyPI 下载：

text 复制代码

https://pypi.org/simple

国内一般推荐使用清华镜像。

设置 pip 全局镜像：

powershell 复制代码

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

验证配置：

powershell 复制代码

pip config list

输出中应包含：

text 复制代码

global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
global.trusted-host='pypi.tuna.tsinghua.edu.cn'

此后所有 pip install 默认都会走清华源。

10. 常见问题：pyenv 安装成功但 python 版本不对

如果执行：

powershell 复制代码

pyenv global 3.12.10
python --version

发现版本不对，通常是 PATH 优先级问题。

排查方式：

powershell 复制代码

where python
where pyenv

正常情况下 python 第一条必须是：

text 复制代码

D:\environment\pyenv-win\.pyenv\pyenv-win\shims\python.exe

如果第一条变成 WindowsApps 或旧 Python 目录，需要调整 PATH 顺序或禁用 App Execution Aliases。

11. 推荐的一次性标准流程总结

最终推荐的稳定流程如下：

清理旧 Python / 旧 pyenv-win PATH
设置 PYENV / PYENV_HOME / PYENV_ROOT 到 D 盘

PATH 加入：

text 复制代码

D:\environment\pyenv-win\.pyenv\pyenv-win\bin
D:\environment\pyenv-win\.pyenv\pyenv-win\shims

关闭 WindowsApps 的 python alias

设置 Python 安装包镜像：

powershell 复制代码

setx PYTHON_BUILD_MIRROR_URL "https://mirrors.huaweicloud.com/python/"

设置 pip 镜像：

powershell 复制代码

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

安装并切换版本：

powershell 复制代码

pyenv install 3.12.10
pyenv global 3.12.10
python -c "import sys; print(sys.executable)"

12. 实际验证结果

最终系统状态如下：

powershell 复制代码

pyenv version
3.12.10 (set by D:\environment\pyenv-win\.pyenv\pyenv-win\version)

python -c "import sys; print(sys.executable)"
D:\environment\pyenv-win\.pyenv\pyenv-win\versions\3.12.10\python.exe

说明：

pyenv-win 正常工作
Python 版本切换生效
Python 安装目录与缓存均位于 D 盘
系统 PATH 解析顺序正确

以上配置完成后，Windows 下的 Python 多版本管理会变得非常干净，环境可控性也会显著提升。