Mac 系统 Python 开发环境搭建：Pyenv + Virtualenv 图文完整方案

1、引言

1.1、Pyenv 简介

Pyenv 是一个用于管理多个 Python 版本的开源工具，允许你在同一台机器上轻松安装、切换和管理不同的 Python 版本，而不会产生冲突。最初由 Yoshinori Kawasaki 开发，现由 Python 社区维护，是 Mac 和 Linux 系统上最受欢迎的 Python 版本管理器之一。

核心功能

✅ 多版本共存

• 安装任意版本的 Python（官方 CPython、PyPy、Jython 等）
• 支持最新 dev 版本、历史旧版本、预发布版本

✅ 全局/局部版本切换

• 全局版本：系统默认 Python 版本
• 局部版本：为特定项目目录设置独立 Python 版本
• Shell 临时版本：当前终端会话临时切换

✅ 版本隔离

• 所有 Python 版本安装在用户目录下，不影响系统 Python
• 无需 sudo 权限即可安装新版本
• 彻底避免破坏系统依赖

✅ 插件生态

• pyenv-virtualenv：集成虚拟环境管理
• pyenv-update：一键更新 Pyenv 本身
• pyenv-installer：简化安装流程

1.2、Virtualenv 简介

Virtualenv 是一个用于创建隔离 Python 环境的工具，它能为每个项目生成独立的虚拟环境，使不同项目的依赖包互不干扰。每个虚拟环境都是一个包含独立 Python 解释器、库和脚本的目录。由 Ian Bicking 创建，是 Python 生态中最经典、最轻量的虚拟环境管理工具，至今仍是许多开发者的首选方案。
核心功能

✅ 依赖隔离

• 每个项目拥有独立的 site-packages 目录
• 不同项目可使用相同包的不同版本（如 Django 3.2 vs 4.2）
• 彻底解决"依赖地狱"问题

✅ 环境复制

• 通过 requirements.txt 轻松复制环境配置
• 支持跨平台、跨机器部署

✅ 轻量纯粹

• 仅专注虚拟环境管理，功能单一
• 不绑定 Python 版本管理
• 速度快，占用资源少

✅ 灵活配置

• 可选择继承或隔离系统全局包
• 支持自定义虚拟环境目录位置

1.3、资源

Pyenv GItHub 地址
Virtualenv GitHub 地址
Virtualenv 官网地址

2、安装

2.1、Pyenv 安装（Git Clone 安装）

2.1.1、通过 Git 安装

# 克隆 pyenv 仓库到本地电脑指定目录
git clone https://github.com/pyenv/pyenv.git /Users/woniu/GItHub/pyenv

2.1.2、配置环境变量

# 配置环境变量（zsh 示例）
echo 'export PYENV_ROOT="/Users/woniu/GItHub/pyenv"' >> ~/.zshrc

echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc

echo 'export PATH="$PYENV_ROOT/shims:$PATH"' >> ~/.zshrc

echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# 使配置生效
source ~/.zshrc

2.1.3、验证安装

# 查看 pyenv 版本
pyenv --version

2.2、安装 pyenv-virtualenv 插件

2.2.1、克隆插件到 pyenv 插件目录

# 克隆插件到 pyenv 插件目录
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

命令解析

• $(pyenv root) 自动获取 pyenv 安装目录
• 插件必须安装在 pyenv/plugins/ 子目录下才能被识别

2.2.2、配置环境变量

# 配置环境变量（zsh 示例）
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc

# 使配置生效
source ~/.zshrc

2.2.3、验证安装

# 检查插件是否被识别
pyenv help | grep virtualenv

# 查看可用的 virtualenv 命令
pyenv virtualenv --help

# 查看 virtualenv 插件版本
pyenv virtualenv --version

2.1、镜像加速

pyenv install 速度过慢，使用国内镜像加速

# 在 ~/.zshrc 或 ~/.bash_profile 中添加
# 加速 GNU 包（解决 readline 下载慢）
echo 'export PYTHON_BUILD_MIRROR_URL="https://mirrors.huaweicloud.com/gnu/"' >> ~/.zshrc

#  加速 Python 源码
echo 'export PYTHON_BUILD_PACKAGE_MIRROR_URL="https://mirrors.huaweicloud.com/python/"' >> ~/.zshrc

# 跳过校验（解决镜像不一致问题）
echo 'export PYTHON_BUILD_MIRROR_URL_SKIP_CHECKSUM=1' >> ~/.zshrc

# 使配置生效
source ~/.zshrc

# 验证两个变量
echo "GNU镜像: $PYTHON_BUILD_MIRROR_URL"
echo "Python镜像: $PYTHON_BUILD_PACKAGE_MIRROR_URL"

3、实战

3.1、Pyenv 基本使用命令

# 查看可安装的 Python 版本
pyenv install --list | grep "^  3."

# 安装指定版本
pyenv install 3.11.8
pyenv install 2.7.18

# 查看已安装 python 版本
pyenv versions

# 设置全局默认版本
pyenv global 3.11.8

# 设置当前项目版本（创建 .python-version 文件）
cd ~/myproject
pyenv local 2.7.18

# 查看 pyenv 当前版本
pyenv version

# 查看 python 当前版本
python --version

3.2、Pyenv - Virtualenv 基本使用命令

# 查看所有虚拟环境
pyenv virtualenvs

# 创建虚拟环境（基于指定 Python 版本）
pyenv virtualenv 3.11.8 myproject-env

# 删除虚拟环境
pyenv uninstall myproject-env
# 或
pyenv virtualenv-delete myproject-env

# 激活虚拟环境（自动切换 Python 版本）
pyenv activate myproject-env

# 退出虚拟环境
pyenv deactivate

# 为项目目录设置本地虚拟环境（推荐）
pyenv local myproject-env
# 这会创建 .python-version 文件，进入目录时自动激活

# 设置全局默认虚拟环境
pyenv global myproject-env

# 查看虚拟环境所在路径
pyenv prefix myproject-env

3.3、新项目配置流程

# 1. 安装所需 Python 版本
pyenv install 3.11.6

# 2. 创建项目虚拟环境
pyenv virtualenv 3.11.6 myproject-env

# 3. 进入项目目录并激活
cd myproject
pyenv local myproject-env

# 验证：查看 Python 路径
which python
# 输出应为：~/.pyenv/versions/myproject-env/bin/python

3.4、虚拟环境中安装 Python 包

3.4.1、pip install 切换镜像源

1、快速解决（临时换源）

# 清华源（推荐）
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests

# 阿里源
pip install -i https://mirrors.aliyun.com/pypi/simple/ pandas

# 中科大源
pip install -i https://pypi.mirrors.ustc.edu.cn/simple/ numpy

# 豆瓣源
pip install -i https://pypi.douban.com/simple/ django

2、永久配置（命令行配置）

# 清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 验证配置
pip config list

激活后，直接使用 pip 安装，无需 sudo：

# 安装单个包
pip install requests pandas numpy

# 从 requirements.txt 批量安装
pip install -r requirements.txt

# 指定版本安装
pip install django==4.2.7

# 卸载包
pip uninstall -y django==4.2.7

# 查看已安装的包
pip list

# 查看某个包的详细信息
pip show requests

# 以 requirements.txt 格式输出（适合导出）
pip freeze

# 检查是否有可更新的包
pip list --outdated

# 统计包的数量
pip list | wc -l

本文教程到此结束，祝愿小伙伴们在编程之旅中能够愉快地探索、学习、成长！