在 Python 开发过程中，经常会遇到需要使用不同版本 Python 的情况。比如，旧项目依赖某个特定的 Python 版本，而新项目则要求使用更新的版本。这时，版本管理工具就显得尤为重要。pyenv-win就是一款专门为 Windows 系统设计的 Python 版本管理工具，它能够让开发者在同一台机器上轻松安装、切换和管理多个 Python 版本。本文将详细介绍pyenv-win的配置方法以及可能遇到的问题和解决办法。​

安装前的准备工作​

1. 安装 Git：pyenv-win依赖于 Git 进行安装和更新。如果你的系统尚未安装 Git，可以前往Git 官网下载安装包进行安装。安装过程中，按照默认设置即可，确保勾选将 Git 添加到系统路径的选项，以便在命令行中能够直接使用 Git 命令。​

1. 安装 Python（可选）：虽然pyenv-win可以管理多个 Python 版本，但首次安装pyenv-win时，系统中至少需要有一个 Python 版本。你可以从Python 官网下载并安装一个 Python 版本。安装时，务必勾选 “Add Python to PATH” 选项，这样系统才能正确识别 Python 命令。​

安装 pyenv-win​

方法一：使用 PowerShell 安装​

1. 以管理员身份打开 PowerShell。在 Windows 搜索栏中输入 “PowerShell”，右键点击 “Windows PowerShell”，选择 “以管理员身份运行”。​

1. 在 PowerShell 中运行以下命令，该命令会从 GitHub 下载并运行pyenv-win的安装脚本：​

​

TypeScript取消自动换行复制

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"​

​

1. 可能遇到的问题及解决办法：​

• 问题：运行上述命令时遇到 “未经授权的访问错误”。​

• 解决办法：再次以管理员身份打开 PowerShell，运行命令Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine，该命令用于设置脚本执行策略，允许运行从互联网下载且经过数字签名的脚本。​

• 问题：遇到 “未数字签名” 错误。​

• 解决办法：执行命令Unblock-File (Join-Path $env:pyenv 'bin/pyenv.ps1')来解除对pyenv脚本的阻止。​

方法二：手动安装​

1. 访问pyenv-win的GitHub 仓库。​

1. 点击页面上的 “Code” 按钮，选择 “Download ZIP” 下载pyenv-win的压缩包。​

1. 创建一个.pyenv文件夹在你的用户目录下。可以通过在 PowerShell 或 Git Bash 中运行命令mkdir $HOME/.pyenv来创建。​

1. 解压下载的pyenv-win.zip文件到刚刚创建的.pyenv目录中。解压后，你应该在$HOME/.pyenv/pyenv-win/bin路径下看到bin目录。​

方法三：使用 Windows 包管理器安装​

1. 使用 Chocolatey 安装：如果你的系统安装了 Chocolatey 包管理器，可以在命令提示符或 PowerShell 中运行命令choco install pyenv-win来安装pyenv-win。​

1. 使用 Scoop 安装：如果使用 Scoop 包管理器，首先在 PowerShell 中运行命令scoop bucket add main添加主存储库，然后运行scoop install main/pyenv来安装pyenv-win。需要注意的是，在撰写本文时，pyenv-win尚未在winget存储库中。​

配置环境变量​

安装完成后，需要配置系统环境变量，确保系统能够正确识别pyenv-win。​

1. 添加 PYENV 变量：按下 Windows 键，搜索 “编辑账户的环境变量” 并打开。在 “用户变量” 部分，点击 “新建” 按钮。​

• 变量名：PYENV​

• 变量值：C:\Users\你的用户名\.pyenv\pyenv-win（请将 “你的用户名” 替换为你实际的 Windows 用户名）​

1. 添加 PYENV_HOME 变量：同样在 “用户变量” 中，点击 “新建”。​

• 变量名：PYENV_HOME​

• 变量值：C:\Users\你的用户名\.pyenv\pyenv-win​

1. 添加 PYENV_ROOT 变量：继续在 “用户变量” 中新建变量。​

• 变量名：PYENV_ROOT​

• 变量值：C:\Users\你的用户名\.pyenv\pyenv-win​

1. 更新 Path 变量：在 “系统变量” 中找到 “Path” 变量，双击打开编辑窗口。点击 “新建”，添加以下两个路径：​

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

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

完成上述操作后，点击 “确定” 保存所有环境变量的更改。​

可能遇到的环境变量配置问题及解决办法​

1. 问题：重启 PowerShell 后，执行pyenv --version提示 "pyenv 不是内部或外部命令"。​

• 解决办法：检查环境变量配置是否正确，确保%USERPROFILE%\.pyenv\pyenv-win\bin和%USERPROFILE%\.pyenv\pyenv-win\shims已添加到系统 Path 变量中；重新打开 PowerShell 窗口或重启电脑使环境变量生效。​

1. 问题：设置了全局 Python 版本，但执行python --version仍显示旧版本。​

• 解决办法：检查系统环境变量中是否存在其他 Python 路径，优先于pyenv的路径，如有则调整顺序；执行pyenv rehash更新 shim 文件。​

验证安装​

重新打开一个新的 PowerShell 窗口（确保不是之前以管理员身份打开的那个），运行命令pyenv --version。如果安装和配置成功，该命令会显示pyenv-win的版本号，例如 “pyenv 2.64.11”。​

使用 pyenv-win 管理 Python 版本​

查看可安装版本​

运行命令pyenv install --list，该命令会列出所有pyenv-win支持安装的 Python 版本（仅限 Windows 预编译版）。列表可能会很长，你可以通过管道符|结合findstr命令进行筛选，例如pyenv install --list | findstr 3.8，这将只列出与 Python 3.8 相关的版本。​

安装指定版本​

使用命令pyenv install <版本号>来安装指定版本的 Python。例如，要安装 Python 3.9.5，运行pyenv install 3.9.5。安装过程可能需要一些时间，期间会从 Python 官方网站下载安装包并进行安装。如果下载速度很慢，可以尝试使用镜像源加速下载，命令格式为pyenv install <版本号> --mirror <镜像源地址>，例如pyenv install 3.9.5 --mirror https://npm.taobao.org/mirrors/python/。另外，也可以手动从 Python 官网下载对应版本的.zip文件，将文件放入~\.pyenv\pyenv-win\install_cache目录下，然后再执行pyenv install <版本号>命令进行安装。​

查看已安装版本​

运行pyenv versions命令，该命令会列出所有已安装的 Python 版本，其中带有*号的版本表示当前激活的版本。​

设置全局默认版本​

使用pyenv global <版本号>命令可以设置全局默认的 Python 版本。例如，pyenv global 3.9.5将把系统的全局默认 Python 版本设置为 3.9.5，在没有其他局部或临时版本设置的情况下，系统将使用该版本的 Python。​

设置局部版本（当前目录）​

在项目目录中，运行pyenv local <版本号>命令可以设置当前目录及其子目录使用的 Python 版本。执行该命令后，会在当前目录下生成一个.python-version文件，文件内容为设置的版本号。当在该目录及其子目录中运行 Python 相关命令时，系统会自动使用该版本的 Python。​

临时切换版本（仅当前会话）​

运行pyenv shell <版本号>命令可以在当前 Shell 会话中临时使用指定版本的 Python。这种设置只在当前打开的 Shell 窗口中有效，关闭窗口后设置失效。​

验证当前 Python 路径​

运行pyenv which python命令，该命令会返回当前使用的 Python 解释器的路径，例如~\.pyenv\pyenv-win\versions\3.9.5\python.exe，通过该路径可以确认当前使用的 Python 版本是否为预期版本。​

更新 pyenv-win​

如果是通过 Chocolatey 安装的pyenv-win，可以使用choco upgrade pyenv-win命令进行更新。如果是通过其他方式安装的，可以运行pyenv update命令来更新pyenv-win的版本数据库缓存，以便获取最新的可安装 Python 版本信息。​

卸载 Python 版本​

使用pyenv uninstall <版本号>命令可以卸载指定版本的 Python。例如，pyenv uninstall 3.9.5将卸载已安装的 Python 3.9.5 版本。在卸载前，请确保该版本没有被当前项目或系统其他部分使用。​

清理缓存和版本​

在安装新版本的 Python 或安装新的 Python 工具后，建议运行pyenv rehash命令。该命令会重新生成pyenv的 shim，确保系统能够正确找到新安装的 Python 版本及其相关工具的可执行文件。​

使用过程中可能遇到的问题及解决办法​

1. 问题：执行pyenv global或pyenv local后，Python 版本未变化。​

• 解决办法：使用pyenv versions查看当前激活的版本，确认设置是否成功；检查项目目录下是否存在.python-version文件，可能被局部设置覆盖。​

1. 问题：使用某个 Python 版本安装了包，但无法导入。​

• 解决办法：确保使用正确的 Python 版本安装包，例如：pyenv shell 3.9.5后再执行pip install package-name；检查包是否安装在对应版本的 site-packages 目录中。​

1. 问题：执行pyenv update时出现网络错误或权限问题。​

• 解决办法：如果是通过包管理器（如 Chocolatey）安装的pyenv-win，使用对应包管理器的更新命令（如choco upgrade pyenv-win）；手动更新：删除~\.pyenv\pyenv-win目录，重新执行安装步骤。​

通过以上步骤，你已经成功安装并配置了pyenv-win，并且能够熟练使用它来管理多个 Python 版本。在实际开发过程中，根据不同项目的需求灵活切换 Python 版本，将大大提高开发效率，避免因版本不兼容导致的各种问题。同时，遇到常见问题时，也能根据上述解决办法快速处理，保障开发顺利进行。