[虚拟环境]pyenv工具(介绍+使用)

一、什么是pyenv？

pyenv是一个强大的Python 解释器版本管理工具，它允许你在同一台电脑上安装、管理和切换多个 Python解释器版本。

pyenv只管理python解释器本身, 负责解释器的安装, 卸载, 切换.

它不负责库包(比如pandas)的安装, 库包的安装还是需要pip.

它解决了在开发中常见的python解释器版本的冲突问题，让不同项目可以使用不同版本的python解释器。

有的项目可能需要python3.5.4, 有的项目可能需要python3.9.5, 有的项目可能需要python3.11.1

所以这个时候,我们就可以使用pyenv工具来在同一台电脑上安装python3.5.4,python3.9.5,python3.11.1, 分别来也执行不同的项目.

二、pyenv的核心作用

1. 多版本管理

• 在同一系统中安装多个 Python 版本
• 可以在 2.x 和 3.x 系列之间随意切换
• 支持 CPython、PyPy、Jython、Stackless 等实现

2. 项目隔离

• 为每个项目指定特定的 Python 版本
• 避免全局 Python 环境被污染

3. 版本切换

• 全局切换：设置整个系统的默认 Python 版本, 用global关键词
• 局部切换：为特定目录（项目）设置 Python 版本, 用local关键词
• Shell 临时切换：仅当前会话使用特定版本, 用shell关键词

4. 依赖管理

• 结合 pyenv-virtualenv 插件，创建独立的虚拟环境
• 隔离项目依赖，避免包冲突

三、pyenv与其他相关工具对比

工具	主要功能	特点
pyenv	Python 版本管理	管理解释器本身
virtualenv/venv	虚拟环境创建	创建隔离的Python运行环境
pipenv	依赖管理+虚拟环境	结合 Pipfile 管理依赖
poetry	依赖管理+打包	现代化的依赖管理和打包工具
conda	包管理+环境管理	科学计算领域的综合工具

注意：pyenv 通常与 virtualenv 或 pyenv-virtualenv 配合使用。

四、pyenv 的工作原理

1. 环境变量重定向

• 通过修改 PATH 环境变量，将指定 Python 版本的路径放在最前面
• 使用 "shims"（垫片）机制拦截 Python 相关命令

2. 目录结构

~/.pyenv/
├── versions/          # 所有安装的Python版本
│   ├── 3.8.10/
│   ├── 3.9.5/
│   └── 3.10.0/
├── shims/             # 所有命令的垫片
├── plugins/           # 插件目录
└── version            # 全局版本文件

3. 优先级顺序

pyenv 按照以下顺序决定使用哪个 Python 版本：

1. PYENV_VERSION 环境变量（最高优先级）
2. .python-version 文件（当前目录）
3. 父目录的 .python-version 文件（向上递归查找）
4. 全局版本（~/.pyenv/version）
5. 系统 Python（最低优先级）

五、安装与配置

1. 自动安装脚本

# 使用官方安装脚本
curl https://pyenv.run | bash

# 或使用以下方式
curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash

2. 手动安装

# 克隆仓库
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

# 配置环境变量（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# 重新加载配置
exec $SHELL

3. 安装编译依赖

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# macOS
brew install openssl readline sqlite3 xz zlib

六、基本使用命令

# 查看有哪些版本 可以 安装 
pyenv install --list

# 安装特定版本
pyenv install 3.9.5     # 安装3.9.5解释器版本
pyenv install 3.10.0    # 安装3.10.0解释器版本
安装后的解释器在~/.pyenv/versions目录下

# 卸载特定版本
pyenv uninstall 3.9.5
pyenv uninstall 3.10.0

# 安装时指定编译选项
PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.9.5

# 查看已经安装的版本(在.pyenv/versions目录下)
pyenv versions

# 查看当前正在使用的版本
pyenv version

# 设置全局版本
pyenv global 3.9.5

# 设置局部版本（当前目录）
pyenv local 3.8.10

# 设置shell临时版本 (当前shell, 关掉shell就失效了)
pyenv shell 3.7.12

# 取消局部版本设置
pyenv local --unset

# 重新生成 shims（安装新包后可能需要）
pyenv rehash

# 查看命令所在路径
pyenv which python
pyenv which pip

# 查看命令的完整路径
pyenv whence python

七、提升下载的速度

使用pyenv install xxx安装Python时速度慢，是因为它会从Python官方服务器下载安装包，

这对国内用户来说网络延迟较高。解决的核心思路是将其下载源更换为国内的镜像服务器。

你可以根据自身的技术偏好，从下表列出的三种方案中选择一种进行操作。

方案	核心思路	操作复杂度	推荐度
方案一：修改pyenv下载源	手动修改pyenv内部的安装脚本，将下载链接替换为国内镜像地址。	中等，需手动查找并编辑文件	⭐⭐⭐⭐
方案二：使用国内加速安装脚本	使用社区维护的、已替换为国内源的pyenv-installer脚本。	简单，一键运行	⭐⭐⭐⭐⭐
方案三：手动下载后离线安装	先从国内镜像站手动下载Python安装包，再让pyenv从本地文件安装。	较低，步骤明确	⭐⭐⭐

1/方案一：修改pyenv下载源（推荐）

这种方法直接修改pyenv内部定义Python版本下载地址的文件。

1. 找到你想安装的python版本的定义文件：在终端中执行 pyenv install --list 查看所有版本，记住你要安装的版本号（如3.10.0）。pyenv的相关文件通常位于 ~/.pyenv/plugins/python-build/share/python-build/ 目录下，你可以在此目录中找到与你目标版本同名的文件。

2. 修改文件内容：用文本编辑器（如vim、nano）打开该文件，找到其中指向 https://www.python.org/ftp/python/ 的URL，将其替换为国内镜像站的地址。

   • 清华大学镜像：https://mirrors.tuna.tsinghua.edu.cn/python/
   • 阿里云镜像：https://mirrors.aliyun.com/python/
   • 腾讯云镜像：https://mirrors.cloud.tencent.com/python/

修改示例(这里用的是清华大学镜像)： 将原链接 https://www.python.org/ftp/python/3.10.0/Python-3.10.0.tar.xz 替换为 https://mirrors.tuna.tsinghua.edu.cn/python/3.10.0/Python-3.10.0.tar.xz。

3. 执行安装：保存文件后，再次运行 pyenv install <version> 即可从国内源高速下载。

2/方案二：使用国内加速安装脚本（最便捷）

如果你尚未安装pyenv，或愿意重新安装，这是最省心的办法。国内开发者将官方安装脚本同步到了Gitee，并替换了其中的仓库地址。

• 你只需在终端中执行以下命令，即可一键安装已配置加速的pyenv：

  curl -L https://gitee.com/jordanxu/pyenv-installer/raw/master/bin/pyenv-installer | bash
  

  这个脚本来自Gitee上的一个开源项目，它修改了pyenv及其插件的Git仓库源。安装完成后，pyenv install 的下载速度通常会得到改善。

3/方案三：手动下载后离线安装

此方法不依赖pyenv的下载脚本，完全手动操作。

1. 下载安装包：直接访问国内镜像站（如清华、阿里云镜像），找到对应版本的 .tar.xz 格式安装包并下载到本地。例如，Python 3.10.0在清华镜像的路径为：https://mirrors.tuna.tsinghua.edu.cn/python/3.10.0/Python-3.10.0.tar.xz。
2. 放置文件：将下载好的文件放入pyenv的缓存目录。该目录通常为 ~/.pyenv/cache/（如果不存在请手动创建）。
3. 执行安装：在终端中运行 pyenv install <version>，pyenv会优先使用缓存目录中的文件进行安装。

注：方案一和方案二本质上都是修改了下载源。如果修改后速度仍不理想，可能是特定镜像节点问题，可尝试更换另一个镜像源地址。

如果你选择了其中一种方法但在具体步骤中遇到问题，可以告诉我你卡在哪一步，以及你使用的操作系统（如macOS或Linux发行版），我可以提供更详细的指导。

八、总结

pyenv 是 Python 开发者的必备工具之一，特别适合需要处理多个项目、不同 Python 版本的情况。通过合理使用 pyenv 和其插件，可以创建干净、隔离的开发环境，提高开发效率，减少环境配置问题。

对于现代 Python 开发，推荐的工作流是：pyenv + pyenv-virtualenv + pip/poetry，这样可以同时管理 Python 解释器版本和项目依赖，确保开发环境的一致性和可重现性。