熊尼玛的七亩地

Python pyenv 开发环境搭建指南

简介

pyenv 是一个强大的 Python 版本管理工具，可以让你在同一台机器上安装和管理多个 Python 版本。配合 pyenv-virtualenv 插件，可以轻松创建和管理独立的虚拟环境，非常适合开发不同项目时使用。

安装 pyenv

macOS

macOS 推荐使用 Homebrew 安装：

1
brew install pyenv

或者使用官方安装脚本：

1
curl https://pyenv.run | bash

Linux (CentOS/RHEL)

1. 安装依赖

1
2
3
4
5
6
7
8
9
# CentOS 7/RHEL 7
sudo yum -y groupinstall "Development Tools"
sudo yum -y install zlib-devel readline-devel sqlite-devel bzip2-devel \
    openssl-devel libffi-devel mysql-devel xz-devel

# CentOS 8+/RHEL 8+ (使用 dnf)
sudo dnf -y groupinstall "Development Tools"
sudo dnf -y install zlib-devel readline-devel sqlite-devel bzip2-devel \
    openssl-devel libffi-devel mysql-devel xz-devel

2. 安装 pyenv

1
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

Linux (Ubuntu/Debian)

1. 安装依赖

1
2
3
4
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 libncurses5-dev \
    libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python3-openssl

2. 安装 pyenv

1
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

配置 Shell 环境

Bash

将以下内容添加到 ~/.bashrc 或 ~/.bash_profile：

1
2
3
4
5
6
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"
fi

Zsh

将以下内容添加到 ~/.zshrc：

1
2
3
4
5
6
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"
fi

应用配置

1
2
3
4
5
# 重新加载 shell 配置
exec "$SHELL"

# 或者
source ~/.bashrc  # 或 source ~/.zshrc

验证安装

1
pyenv --version

安装 Python 版本

查看可用的 Python 版本

1
pyenv install --list

安装指定版本

1
2
3
4
5
6
7
8
# 安装最新的 Python 3.12
pyenv install 3.12.0

# 安装 Python 3.11
pyenv install 3.11.6

# 安装 Python 3.10
pyenv install 3.10.13

注意：Python 3.5 及以下版本已经不再维护，建议使用 Python 3.8 或更高版本。

设置全局默认版本

1
pyenv global 3.12.0

设置项目本地版本

1
2
cd /path/to/your/project
pyenv local 3.11.6

这会在项目目录下创建 .python-version 文件。

查看已安装的版本

1
pyenv versions

查看当前使用的版本

1
pyenv version

安装 pyenv-virtualenv 插件

pyenv-virtualenv 是 pyenv 的插件，用于创建和管理虚拟环境。

安装插件

1
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

配置 Shell（如果还没有配置）

在 ~/.bashrc 或 ~/.zshrc 中添加：

1
eval "$(pyenv virtualenv-init -)"

然后重新加载 shell：

1
exec "$SHELL"

使用虚拟环境

创建虚拟环境

1
2
3
4
5
# 基于全局 Python 版本创建虚拟环境
pyenv virtualenv 3.12.0 myproject

# 基于指定版本创建虚拟环境
pyenv virtualenv 3.11.6 myproject-env

激活虚拟环境

1
2
3
4
5
6
# 方法 1：使用 pyenv activate
pyenv activate myproject

# 方法 2：使用 pyenv local（推荐）
cd /path/to/your/project
pyenv local myproject

停用虚拟环境

1
pyenv deactivate

删除虚拟环境

1
pyenv uninstall myproject

列出所有虚拟环境

1
pyenv virtualenvs

常用命令总结

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 查看 pyenv 版本
pyenv --version

# 查看可安装的 Python 版本
pyenv install --list

# 安装 Python 版本
pyenv install 3.12.0

# 查看已安装的版本
pyenv versions

# 设置全局版本
pyenv global 3.12.0

# 设置本地版本
pyenv local 3.12.0

# 创建虚拟环境
pyenv virtualenv 3.12.0 myenv

# 激活虚拟环境
pyenv activate myenv

# 停用虚拟环境
pyenv deactivate

# 删除虚拟环境
pyenv uninstall myenv

# 列出所有虚拟环境
pyenv virtualenvs

实际使用示例

场景 1：为新项目创建虚拟环境

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 创建项目目录
mkdir my-new-project
cd my-new-project

# 2. 创建虚拟环境（基于 Python 3.12）
pyenv virtualenv 3.12.0 my-new-project

# 3. 设置项目使用该虚拟环境
pyenv local my-new-project

# 4. 验证 Python 版本
python --version

# 5. 安装项目依赖
pip install -r requirements.txt

场景 2：切换不同项目的 Python 版本

1
2
3
4
5
6
7
# 项目 A 使用 Python 3.11
cd /path/to/project-a
pyenv local 3.11.6

# 项目 B 使用 Python 3.12
cd /path/to/project-b
pyenv local 3.12.0

常见问题

1. 安装 Python 版本时编译失败

问题：缺少必要的开发库。

解决方案：

  • 确保已安装所有依赖（参考上面的依赖安装步骤）
  • 对于 CentOS/RHEL，确保安装了 Development Tools 组
  • 检查错误日志，安装缺失的库

2. pyenv 命令找不到

问题：Shell 配置未正确加载。

解决方案：

  • 检查 ~/.bashrc 或 ~/.zshrc 中的配置是否正确
  • 执行 source ~/.bashrc 或 source ~/.zshrc
  • 确认 $PYENV_ROOT/bin 在 $PATH 中

3. 虚拟环境激活后提示符没有变化

问题：pyenv-virtualenv-init 未正确配置。

解决方案：

  • 确保在 shell 配置文件中添加了 eval "$(pyenv virtualenv-init -)"
  • 重新加载 shell 配置

4. 安装 Python 版本速度慢

问题：从源码编译 Python 需要时间。

解决方案：

  • 这是正常现象，编译过程可能需要 10-30 分钟
  • 可以使用 pyenv install -v 查看详细编译过程
  • 考虑使用预编译的二进制版本（如果可用）

最佳实践

  1. 使用项目本地版本：为每个项目设置 pyenv local，确保团队成员使用相同的 Python 版本
  2. 定期更新：定期更新 pyenv 和 Python 版本
    1
    cd ~/.pyenv && git pull
  3. 使用虚拟环境：每个项目使用独立的虚拟环境，避免依赖冲突
  4. 版本锁定：在项目中添加 .python-version 文件到版本控制
  5. 清理旧版本：定期清理不再使用的 Python 版本和虚拟环境

参考资源

更新说明：本文已更新至 2024 年，包含最新的安装方法和最佳实践。Python 3.5 已不再维护，建议使用 Python 3.8 或更高版本。

0%