pyenv
让你可以轻松切换多个Python 版本。

对你有帮助？赞助用于服务器

更新日期 2025-05-09 pyenv 2.5.7 pyenv

pyenv是什么

pyenv 让你可以轻松切换多个 Python 版本。它简单、低调，并遵循 UNIX 统一规范。

pyenv功能特点

  • 允许你按用户更改全局 Python 版本。
  • 支持每个项目指定 Python 版本。
  • 允许你通过环境变量覆盖 Python 版本。
  • 可以同时从多个Python版本中查找命令，这对于用 tox 跨版本测试很有帮助。

不同，pyenv与 pythonbrew 和 pythonz 不同

  • 依赖 Python 本身。pyenv 完全由 shell 脚本编写，无需 Python 启动。
  • 需要加载到你的 shell。pyenv 采用 shim 机制，只需将目录加入 `PATH`。
  • 管理 virtualenv。你可以自己创建 virtualenv，或用 pyenv-virtualenv 自动化。

pyenv安装

Linux/Unix

如果你已安装 Homebrew，MacOS的 Homebrew 选项同样适用。

1. 自动安装器（推荐） 

curl -fsSL https://pyenv.run | bash

MacOS

上面Linux部分的选项也可以使用，但建议基本使用Homebrew。

Homebrew(macOS 下)

更新 homebrew 并安装 pyenv：

brew update
brew install pyenv

若要安装（并更新到）Pyenv 的最新开发版，请运行：

brew install pyenv --head

然后按照安装后的其余步骤进行操作，从为Pyenv设置shell环境开始。

可选：修复 brew doctor 的警告 config 脚本存在于系统或 Homebrew 目录之外

如果你要从源码构建 Homebrew 配方并链接 Python（如 Tkinter 或 NumPy） （一般仅开发者或使用 EOL版 macOS 且需源码安装的用户需要）

为避免意外链接到 Pyenv 提供的 Python，在 shell 配置中加入：

Bash/Zsh: 
alias brew='env PATH="${PATH//$(pyenv root)\/shims:/}" brew'

Fish: 
alias brew="env PATH=(string replace (pyenv root)/shims '' \"$PATH\") brew"

pyenv for Windows

Pyenv 官方不支持 Windows，且在 Windows 下无法运行（除非在 WSL）。 此外，即使在 WSL，安装的 Python 也是 Linux 版而非原生 Windows 版， 因此无法获得 Windows 特有功能。

在 Windows 下，推荐使用 pyenv-win

它可安装原生 Windows Python。

PowerShell下安装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.重新打开PowerShell

  • 执行 pyenv --version 输入已安装的pyenv版本号
  • 执行 pyenv install -l检测可安装的版本Python版本列表
  • 执行 pyenv install 安装指定Python版本
  • 执行 pyenv global 设置 pythone全局版本
pyenv pyenv pyenv

pyenv-win 命令行大全

pyenv local        设置或显示特定应用程序的本地Python版本
pyenv latest       打印带有指定前缀的最新已安装或已知版本
pyenv global       设置或显示全局Python版本
pyenv shell        设置或显示特定shell的Python版本
pyenv install      安装一个或多个Python版本
pyenv uninstall    卸载一个或多个Python版本
pyenv update       更新缓存的版本数据库
pyenv rehash       重新生成pyenv shims（切换Python版本后运行此命令）
pyenv vname        显示当前Python版本
pyenv version      显示当前Python版本及其来源
pyenv version-name 显示当前Python版本
pyenv versions     列出pyenv可用的所有Python版本
pyenv exec         运行可执行文件（首先配置PATH，使所选Python版本的`bin'目录位于最前端）
pyenv which        显示可执行文件的完整路径
pyenv whence       列出包含指定可执行文件的所有Python版本

Powershell禁止运行脚本

原因是Windows新的权限执行策略改变,在PowerShell里面执行命令：

Get-ExecutionPolicy
Get-ExecutionPolicy

若要更改执行策略，以管理员身份打开PowerShell，然后使用以下命令之一设置执行策略

Set-ExecutionPolicy RemoteSigned

更改执行策略的步骤 首先，需要了解PowerShell中的执行策略级别。执行策略有几种级别，包括：

  • Restricted：默认策略，不允许任何脚本运行。
  • AllSigned：只允许运行由可信发布者签名的脚本。
  • RemoteSigned：允许运行本地脚本；远程脚本必须由可信发布者签名。
  • Unrestricted：允许运行所有脚本，但会警告用户执行来自Internet的脚本。
Get-ExecutionPolicy

为 Pyenv 配置 shell 环境

以下设置适用于绝大多数常见场景。更多高级配置见[高级配置]

Bash

各发行版 Bash 启动文件差异较大，最可靠的方式是将 Pyenv 配置命令同时添加到 `.bashrc`（交互式 shell）和 Bash 使用的 profile 文件（登录 shell）。

1.首先，运行以下命令将配置添加到 ~/.bashrc：

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc

2.若有 ~/.profile、~/.bash_profile 或 ~/.bash_login，也添加配置。若都没有，则新建 ~/.profile 并添加：

添加到 ~/.profile

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init - bash)"' >> ~/.profile

添加到 ~/.bash_profile

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init - bash)"' >> ~/.bash_profile

Zsh

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

若需在非交互式登录 shell 也启用 Pyenv，也请添加到 ~/.zprofile 或 ~/.zlogin。

Fish

1. Fish 3.2.0 及以上，交互执行：

set -Ux PYENV_ROOT $HOME/.pyenv
fish_add_path $PYENV_ROOT/bin

2.其他版本执行：

set -Ux PYENV_ROOT $HOME/.pyenv
set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths

3.再将以下内容加入 ~/.config/fish/config.fish：

pyenv init - fish | source

重启 shell

exec "$SHELL"

pyenv命令行用法

pyenv命令行用法

用 pyenv install 安装其他Python 版本。

pyenv install 3.10.4

运行 pyenv install -l 可列出所有可用版本。

关于 Python 发行版的说明

注意：大多数 Pyenv 提供的 Python 版本为源码包，安装时需编译（因此需预装构建依赖）。 可通过传递参数自定义构建，详见 [Python-Build 的特殊环境变量](plugins/python-build/README.md#special-environment-variables)。

注意： 需用代理下载时，请设置 `http_proxy` 和 `https_proxy` 环境变量。

注意： 若想获得更快的解释器（但构建时间更长），详见 [最大性能构建](plugins/python-build/README.md#building-for-maximum-performance)。

前缀自动解析到最新版本

除 uninstall 外，所有 Pyenv 子命令会自动将前缀解析为对应版本线的最新版本。

pyenv install 选择最新已知版本，其他子命令选择最新已安装版本。

例如，安装并切换到最新 3.10 版本：

pyenv install 3.10
pyenv global 3.10

可用 pyenv latest -k 查看 pyenv install 如何解析前缀，或 pyenv latest 查看其他子命令的解析。

扩展支持的 Python 版本

以下 Python 版本，Pyenv 应用用户补丁以支持新环境。
虽然我们不主动维护这些补丁，但只要旧版不变，通常能继续使用，除非新环境有不兼容变更。

  • 3.7.8-3.7.15, 3.8.4-3.8.12, 3.9.0-3.9.7 : XCode 13.3
  • 3.5.10, 3.6.15 : MacOS 11+ 和 XCode 13.3
  • 2.7.18 : MacOS 10.15+ 和 Apple Silicon

切换 Python 版本

要选择 Pyenv 安装的 Python 版本，运行：

pyenv shell —— 仅当前 shell 会话有效
pyenv local —— 当前目录及子目录自动选择
pyenv global —— 全局（用户级）选择

如将新装的 Python 3.10.4 设为首选：

   
pyenv global 3.10.4

此后运行 python、pip 等命令时，将优先使用 Pyenv 提供的 3.10.4。 用 system 作为版本名可重置为系统自带 Python。

同时启用多个版本

可同时指定多个 Python 版本。例如同时用最新的 CPython 3.11 和 3.12：

pyenv global 3.11 3.12

卸载 Python 版本

随着时间推移，你会在 $(pyenv root)/versions 目录积累多个 Python 版本。 用 pyenv uninstall 卸载旧版本

也可直接 rm -rf 目标版本目录。用 pyenv prefix 可查找某版本目录，如 pyenv prefix 2.6.8。
注意插件可能在卸载时有额外操作，如 Pyenv-Virtualenv 会移除相关虚拟环境。

其他操作

运行 pyenv commands 查看所有子命令。 加 --help 查看子命令帮助，或查阅 [命令参考](COMMANDS.md)。 注意安装的 Pyenv 插件也可能添加自定义子命令。

pyenv升级

用 Homebrew 升级

用 Homebrew 安装的 Pyenv，可用：

brew upgrade pyenv

如需切换到开发版：

brew uninstall pyenv
brew install pyenv --head

之后可用 `brew upgrade pyenv` 正常升级。

卸载 pyenv

pyenv 结构简单，临时禁用或卸载都很方便。

1. 禁用 pyenv 只需移除 shell 启动配置中的 `pyenv init`，这样 shims 目录会从 `PATH` 移除，后续 `python` 等命令会恢复为系统自带。`pyenv` 仍可在命令行用，但不会影响 Python 版本切换。

2. 彻底卸载 pyenv，移除所有 shell 配置后，删除根目录（会删除所有 pyenv 安装的 Python 版本）：

rm -rf $(pyenv root)

若用包管理器安装，最后一步卸载包，如 Homebrew：

brew uninstall pyenv

工作原理

pyenv 通过在 `PATH` 前插入 shim 可执行文件，拦截 Python 命令，判断所需 Python 版本，并将命令转发到正确的 Python 安装。

理解 PATH

运行 `python` 或 `pip` 时，shell 会在 `PATH` 指定的目录列表中查找可执行文件，目录间用冒号分隔：/usr/local/bin:/usr/bin:/bin

`PATH` 从左到右查找，前面的目录优先。

理解 Shims

pyenv 通过在 `PATH` 前插入 shim 目录实现：$(pyenv root)/shims:/usr/local/bin:/usr/bin:/bin

pyenv 通过 rehash 机制维护 shim，确保每个已安装 Python 版本的命令（如 `python`、`pip`）都有 shim。

shim 是轻量可执行文件，会将命令转发给 pyenv。所以安装 pyenv 后，运行 pip 时，系统会：

  • 在 PATH 查找 pip 可执行文件
  • 在最前面的 shim 目录找到 pip
  • 运行 shim，shim 再调用 pyenv

理解 Python 版本选择

执行 shim 时，pyenv 按以下顺序决定使用哪个 Python 版本：

  • 1. `PYENV_VERSION` 环境变量（如有）。可用 [`pyenv shell`](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-shell) 设置。
  • 2. 当前目录下的 `.python-version` 文件（如有）。可用 [`pyenv local`](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-local) 修改。
  • 3. 向上查找父目录中的第一个 `.python-version` 文件。
  • 4. 全局 `$(pyenv root)/version` 文件。可用 [`pyenv global`](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-global) 修改。若无则默认用 "system"。 特殊版本名 "system" 表示用 shim 目录后 `PATH` 中的 Python。
  • pyenv是什么
  • pyenv功能特点
  • 安装 pyenv For Linux/MacOS
  • 安装pyenv for Windows
  • Powershell禁止运行脚本
  • Pyenv 配置 shell 环境
  • pyenv命令行用法
  • pyenv升级
  • 卸载 pyenv
  • 赞助我们