pyenv怎么安装和切换python版本
详细介绍pyenv在macOS和Linux系统下的安装方法、Shell环境变量配置、编译安装指定Python版本的步骤，以及使用global、local和shell命令切换与验证Python版本的完整流程。
假设你的电脑上同时有两个项目：一个维护中的旧服务依赖 Python 3.8，另一个新项目需要使用 Python 3.12。如果直接覆盖系统自带的 Python，往往会导致系统工具或旧项目无法运行。使用 pyenv 可以把多个版本的 Python 安装在用户目录下的独立文件夹中互不干扰，并通过 pyenv global、pyenv local 和 pyenv shell 三条命令按全局、项目目录或当前终端会话灵活切换。
下面按实际操作顺序，说明在 macOS 与 Linux 系统中如何准备编译依赖、安装 pyenv、配置 Shell 环境变量、安装目标 Python 版本，以及切换和验证当前生效版本。
一、先理解 pyenv 切换版本的基本原理
很多初次使用 pyenv 的人会跳过环境变量配置，或者疑惑为什么切换版本后不用修改系统文件。理解它的工作方式，能帮你避开大多数配置失效的问题。
pyenv 本身不修改系统目录中的 Python，而是将每个安装好的版本放在 ~/.pyenv/versions/ 下的独立子目录里，例如 ~/.pyenv/versions/3.12.3/。同时，pyenv 会在系统 PATH 环境变量的最前面插入一个名为 ~/.pyenv/shims 的垫片目录。
当你在终端里输入 python 或 pip 时，系统会优先命中 shims 目录中的同名脚本。该脚本会依次检查当前终端变量、当前目录以及用户全局配置，确定这次该用哪个版本号，再把命令转发给对应的真实可执行文件。
二、安装前的环境准备
原生 pyenv 面向 macOS 和 Linux 系统设计，采用源码下载后在本地编译的方式安装 Python。如果使用的是 Windows 系统，需要改用独立的 pyenv-win 项目，命令与配置方式不同，不在本篇操作范围内。
由于 pyenv 会在本地编译 Python 源码，动手安装 pyenv 之前，需要先装齐编译器和常见的系统库头文件，否则后续安装 Python 时容易出现缺少 zlib、openssl 或 sqlite3 的报错。
macOS 准备步骤
打开 macOS 的“终端”应用，先安装 Xcode 命令行工具，再使用 Homebrew 安装编译所需的依赖库：
终端命令（macOS）xcode-select --install
brew install openssl readline sqlite3 xz zlib tcl-tk如果系统已经安装过 Xcode 命令行工具，执行第一条命令后会提示已安装，直接运行第二条 brew install 命令即可。
Ubuntu / Debian 准备步骤
在 Ubuntu 或 Debian 终端中，先更新软件源索引，再安装编译工具链和基础开发库：
终端命令（Ubuntu / Debian）sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev如果你使用的是 CentOS、RHEL 或 Fedora 等基于 dnf / yum 的发行版，需要安装对应的 gcc、make 以及 zlib-devel、openssl-devel 等 -devel 结尾的开发包，具体列表可在 pyenv 官方 GitHub 仓库的 Build Environment 文档中核对。
三、安装 pyenv 并配置 Shell 环境
准备好依赖后，安装 pyenv 分为两步：下载程序本体，以及把环境变量写入 Shell 配置文件。完成这两步并重载终端后，pyenv 才能正常拦截和切换版本。
1. 安装 pyenv 本体
在 macOS 上直接使用 Homebrew 安装最省事，命令如下：
终端命令（macOS）brew install pyenv在 Linux 上，通常使用官方提供的安装脚本直接克隆到 ~/.pyenv 目录：
curl -fsSL https://pyenv.run | bash该脚本会同时安装 pyenv 核心程序及常用的 pyenv-virtualenv 等配套插件；如果需要核对最新安装说明，可以在 GitHub 上查阅 pyenv/pyenv 官方仓库的 README。
2. 配置 Shell 启动文件
安装完成后，必须把 pyenv 的路径和初始化脚本加入 Shell 配置文件，否则终端找不到 pyenv 命令，也无法激活 shims 垫片。
先用 echo $SHELL 确认你当前使用的 Shell。macOS 默认通常是 /bin/zsh（Zsh），大多数 Linux 发行版默认是 /bin/bash（Bash）。
如果使用的是 Zsh，将下面三行追加到用户主目录下的 ~/.zshrc 文件末尾：
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"如果使用的是 Bash，将下面三行追加到 ~/.bashrc（若为 macOS 上的 Bash 登录终端，还需同步检查 ~/.bash_profile 是否加载了 ~/.bashrc）：
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"注意位置差异：如果你在 macOS 上通过 Homebrew 安装 pyenv，pyenv 命令本身已经位于 Homebrew 的路径中，但依然建议保留上面的 PYENV_ROOT 和 eval "$(pyenv init - ...)"，因为它们负责将 ~/.pyenv/shims 放到 PATH 最前面。
3. 重载终端并验证
保存配置文件后，重新打开一个终端窗口，或者在当前终端执行以下命令重启 Shell 会话：
终端命令exec "$SHELL"接着运行版本查询命令，确认 pyenv 已可正常调用：
pyenv --versionpyenv 2.4.12四、使用 pyenv 安装指定的 Python 版本
在切换版本之前，先要把需要的 Python 解释器安装到本地。下面以常见的 Python 3.11 和 3.12 系列为例，展示从查找可安装版本到验证安装结果的完整过程。
1. 查看可安装的 Python 版本
pyenv 支持安装的标准 CPython、Anaconda、PyPy 等解释器非常多，直接列出全部内容会很长，通常配合 grep 筛选出自己需要的大版本：
pyenv install --list | grep -E "^\s*3\.(11|12)\." 3.11.8
3.11.9
3.12.2
3.12.32. 下载并编译安装目标版本
从上面的列表中选定精确版本号，然后执行 pyenv install。例如安装 3.11.9 和 3.12.3：
pyenv install 3.11.9
pyenv install 3.12.3执行期间 pyenv 会从 Python 官方源下载源码压缩包并在本地编译，通常需要几分钟。若出现连续几分钟无新输出，属于正在编译的正常现象，不要随意按 Ctrl+C 中断；如果下载阶段长时间卡住，通常是网络访问源码镜像较慢所致。
版本提示：你也可以只输入主次版本号（如 pyenv install 3.12），较新版本的 pyenv 会自动匹配该分支最新的稳定小版本。不过在团队协作时，建议明确写出完整三位版本号，方便成员保持环境一致。
3. 查看本地已安装的版本
安装完成后，用 pyenv versions（注意末尾是复数 versions）检查目前机器上有哪些可用版本：
pyenv versions* system (set by /Users/demo/.pyenv/version)
3.11.9
3.12.3输出中带有星号 * 的一行，表示当前正在生效的 Python 版本。此时还没有切换，因此默认指向 system（系统自带 Python）。
五、切换 Python 版本的三种方式与验证
pyenv 提供了三条切换命令，分别对应“当前终端会话”、“指定项目目录”和“用户全局默认”三种不同作用域。理解它们的生效范围和优先级，就能灵活应对不同项目。
1. 切换全局默认版本：pyenv global
如果你想把 3.12.3 设为日常打开终端时的默认 Python 版本，运行 pyenv global：
pyenv global 3.12.3这条命令会把版本号写入 ~/.pyenv/version 文件中。此后在任何未单独指定版本的目录下，都会默认使用 3.12.3。如果以后需要退回系统默认 Python，可以执行 pyenv global system。
2. 为单个项目目录切换版本：pyenv local
回到开头的场景：全局已经设为 3.12.3，但旧项目目录 ~/projects/legacy-api 必须运行在 3.11.9 上。进入该项目根目录后执行 pyenv local：
cd ~/projects/legacy-api
pyenv local 3.11.9执行后，当前目录下会生成一个隐藏文件 .python-version（内容就是 3.11.9）。以后只要 cd 进入该目录或其子目录，Python 会自动切换为 3.11.9；离开该目录后，又会自动恢复为全局的 3.12.3。如果想取消该目录的独立设置，运行 pyenv local --unset（会删除 .python-version 文件）。
3. 临时切换当前终端会话：pyenv shell
如果你只是想在当前终端窗口里临时用另一个版本跑一次脚本，不希望修改项目文件或全局配置，可以使用 pyenv shell：
pyenv shell 3.11.9它的原理是在当前终端进程中设置环境变量 PYENV_VERSION。因为优先级最高，它会暂时覆盖 local 和 global 的设置；关闭终端窗口或者执行 pyenv shell --unset 后就会失效。
4. 验证切换是否真正生效
切换完成后，建议同时用下面三条命令确认路径和版本，不要只看 pyenv version 的提示：
pyenv version
which python
python --version3.11.9 (set by /Users/demo/projects/legacy-api/.python-version)
/Users/demo/.pyenv/shims/python
Python 3.11.9当 which python 返回的路径位于 ~/.pyenv/shims/python，且 python --version 输出与目标一致时，说明切换已经完全生效；对应的 pip 也会同步指向该版本下的 pip。
六、安装与切换过程中的常见问题
下面列出几个在使用 pyenv 安装或切换阶段最容易遇到的问题，按出现频率排查即可。
| 常见现象 | 主要原因 | 处理方法 |
|---|---|---|
执行 pyenv 提示 command not found |
Shell 启动文件未配置，或修改错了配置文件 | 确认 echo $SHELL 结果，Zsh 修改 ~/.zshrc，Bash 修改 ~/.bashrc，保存后执行 exec "$SHELL" |
已执行 pyenv global 或 local，但 python --version 没变化 |
shims 目录未排在 PATH 最前面，或被高优先级设置覆盖 |
运行 which python，若仍指向 /usr/bin/python 等系统路径，检查初始化命令是否写在配置文件末尾；若 pyenv version 显示 PYENV_VERSION，执行 pyenv shell --unset |
pyenv install 编译失败，报错缺少 ssl、zlib 或 sqlite3 |
安装 Python 前缺少对应的系统开发头文件 | 补齐第二节列出的编译依赖库后，重新执行 pyenv install <版本号> |
安装了第三方库提供的命令行工具（如 pytest）却找不到 |
旧版 pyenv 未刷新垫片索引 | 使用 pip install 安装带可执行命令的包后，运行一次 pyenv rehash 更新 shims |
如果后续需要清理不再使用的旧版本，直接执行 pyenv uninstall <版本号>（例如 pyenv uninstall 3.11.9）即可将该版本的独立目录完整删除，不会影响其他已安装的 Python 版本。
本站声明
本文内容仅供参考，不代表本站观点。转载或引用请注明出处。如发现内容问题，请通过联系我们页面反馈。
