Windows 环境下 pyenv-win 全指南

在 Python 领域，pyenv 同样是版本管理的“黄金标准”。本文详细介绍了如何在 Windows 环境下通过 pyenv-win 实现多版本 Python 的安装与自动切换，并保留了真实的终端执行记录，助你彻底解决环境冲突。

为什么选择 pyenv？

Python 的环境管理通常分为两个维度：

1. 版本管理：在不同大版本（如 3.10, 3.13）之间自由切换。

2. 虚拟环境管理：隔离不同项目的第三方依赖包。

如果你在找一个和 nvm 逻辑一模一样的工具，那么 pyenv 是唯一首选。它专注于 Python 版本的安装与切换，简单而纯粹。

在 Windows 上安装 pyenv-win

原生的 pyenv 是为 Unix/Linux/macOS 设计的。在 Windows 环境下，我们需要使用其移植版：pyenv-win。

1. 准备工作：解锁脚本权限

首次在 PowerShell 执行下载脚本前，建议先放行权限拦截：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

为什么要这么做？ Windows 默认禁止运行未签名的本地脚本。此命令允许运行你亲自下载的脚本，仅针对当前用户，兼顾了安全性。

2. 执行一键安装命令

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" | [System.IO.File]::WriteAllLines("$HOME\install-pyenv-win.ps1", $input); & "$HOME\install-pyenv-win.ps1"

执行过程记录：

PS C:\Users\admin> Invoke-WebRequest -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "$HOME\install-pyenv-win.ps1"
PS C:\Users\admin> & "$HOME\install-pyenv-win.ps1"

    目录: C:\Users\admin

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----          2026/4/3     22:43                .pyenv
pyenv-win is successfully installed. You may need to close and reopen your terminal before using it.

3. 环境变量检查（关键）

脚本跑完后，请确保 pyenv 拥有“最高统治权”：

1. 搜索并打开 “环境变量”。

2. 在 “用户变量” 中找到 Path，双击进入。

3. 确保以下两个路径排在列表最顶端（高于任何其他 Python 路径）：

   • %USERPROFILE%\.pyenv\pyenv-win\bin

   • %USERPROFILE%\.pyenv\pyenv-win\shims

4. 验证安装

重启终端，输入：

pyenv --version
# 成功将返回：pyenv 3.1.1

安装与激活 Python 版本

1. 安装 Python 3.13.0

PowerShell

pyenv install 3.13.0

执行过程记录：

PS C:\Users\admin> pyenv install 3.13.0
:: [Info] ::  Mirror: https://www.python.org/ftp/python
:: [Downloading] ::  3.13.0 ...
:: [Installing] ::  3.13.0 ...
:: [Info] :: completed! 3.13.0

2. 激活并设置为默认版本

安装后需要手动指定版本，否则系统仍找不到 python 命令。

PowerShell

# 将 3.13.0 设置为全局默认版本
pyenv global 3.13.0

# 刷新状态（确保垫片生效）
pyenv rehash

执行过程记录：

PS C:\Users\admin> python --version
No global/local python version has been set yet...
PS C:\Users\admin> pyenv global 3.13.0
PS C:\Users\admin> pyenv rehash
PS C:\Users\admin> python --version
Python 3.13.0

💡 进阶：局部版本切换的“魔法”

这是 pyenv 最强大的地方。如果你有一个旧项目需要 Python 3.10，只需进入项目文件夹执行：

PowerShell

pyenv local 3.10.x

• 自动感应：当你在这个文件夹里运行 python 时，它是 3.10。

• 无缝切回：一旦你 cd .. 离开这个文件夹，python 版本会自动变回全局默认的 3.13.0。

这种隔离体验让你无需再为不同项目的版本依赖而头疼。

（完）