在Python开发中，「版本冲突」是新手最常踩的坑——比如Stable Diffusion要求Python 3.10.x，而你的其他项目需要3.11+；手动安装多个版本后环境变量混乱，执行python --version永远不是想要的版本……
pyenv 正是解决这类问题的「神器」：它能让你在单台电脑上无痛管理多个Python版本，一键切换、全局/局部隔离，彻底告别版本冲突和环境变量配置的烦恼。本文会从核心概念到实战操作，完整讲解pyenv（及Windows下的pyenv-win）的使用。
一、什么是pyenv？
1. 核心定义
pyenv 是一款轻量级的Python版本管理工具，最初为Linux/macOS设计，pyenv-win 是其Windows移植版，核心目标是：
- 版本隔离：多个Python版本（如3.8、3.10.19、3.11）共存且互不干扰；
- 灵活切换：可为全局系统、单个项目指定不同Python版本；
- 无需管理员权限：版本安装在用户目录，无需修改系统级配置；
- 零侵入：不修改系统原有Python，仅通过环境变量临时接管调用。
2. 为什么不用手动安装？
对比手动安装Python的痛点，pyenv 的优势一目了然：
| 方式 | 痛点 | pyenv解决方案 |
|---|
| 手动安装 | 版本冲突、环境变量配置复杂、切换麻烦 | 一键切换版本，自动管理环境变量 |
| 系统自带Python | 权限不足（Linux/macOS）、版本过旧 | 安装用户级版本，不影响系统版本 |
| 多项目开发 | 不同项目依赖不同Python版本 | 为项目目录指定专属版本（局部生效） |
二、核心原理（新手可略过）
pyenv 本质是通过「路径劫持」实现版本切换：
- 它会在系统
PATH最前端插入自己的shims（垫片）目录； - 当你执行
python/pip命令时，系统优先调用shims中的脚本； shims根据你设置的版本（全局/局部），转发命令到对应的Python可执行文件。
简单说：pyenv 是Python命令的「路由器」，决定哪个版本的Python响应你的指令。
三、安装与基础配置
1. Linux/macOS 安装pyenv
推荐用官方自动安装脚本（需先安装git）：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| # 安装pyenv
curl https://pyenv.run | bash
# 配置环境变量（根据终端类型选择，bash/zsh）
# bash用户（~/.bashrc）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
# zsh用户（~/.zshrc）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
# 生效配置
source ~/.bashrc # 或 source ~/.zshrc
# 验证安装
pyenv --version
|
2. Windows 安装pyenv-win
Windows无原生pyenv，需安装pyenv-win，两种方式可选：
方式1：PowerShell自动安装（推荐）
以管理员身份打开PowerShell，执行：
1
2
3
4
5
| # 允许执行脚本（仅临时生效）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# 自动安装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"
|
安装完成后重启终端，执行pyenv --version验证。
方式2：手动安装（解决网络问题）
如果自动安装失败，手动下载解压：
- 下载地址：https://github.com/pyenv-win/pyenv-win/archive/refs/tags/v3.1.1.zip
- 解压到
%USERPROFILE%\.pyenv（如C:\Users\你的用户名\.pyenv）； - 将
%USERPROFILE%\.pyenv\pyenv-win\bin和%USERPROFILE%\.pyenv\pyenv-win\shims添加到系统环境变量PATH； - 重启终端验证。
四、pyenv 核心操作（通用）
以下命令在Linux/macOS/Windows（pyenv-win）下均适用，重点适配你关注的「安装Python 3.10.19」场景。
1. 查看可安装的Python版本
1
2
3
4
5
| # 列出所有可安装的版本（会显示3.10.19、3.11.9等）
pyenv install --list
# 过滤查找指定版本（更高效）
pyenv install --list | grep "3.10" # 查找3.10系列
|
2. 安装指定Python版本
1
2
3
4
5
6
7
| # 安装Python 3.10.19（SD最兼容版本）
pyenv install 3.10.19
# 【Windows提速】手动下载安装包到缓存目录
# 1. 下载python-3.10.19-amd64.exe到 %USERPROFILE%\.pyenv\pyenv-win\install_cache
# 2. 再执行安装命令，会自动识别本地包
pyenv install 3.10.19
|
3. 查看已安装的版本
1
2
3
4
| pyenv versions
# 输出示例（*表示当前生效版本）：
# 3.10.19
# * 3.11.9 (set by /Users/xxx/.pyenv/version)
|
4. 切换Python版本
（1）全局版本（系统默认）
1
2
3
4
5
| # 设置全局默认版本为3.10.19
pyenv global 3.10.19
# 验证
python --version # 输出Python 3.10.19
|
（2）局部版本（项目专属，推荐）
为Stable Diffusion项目指定3.10.19，不影响其他项目：
1
2
3
4
5
6
7
8
9
10
11
12
| # 进入SD根目录
cd F:\stable-diffusion-webui
# 设置局部版本（会生成.python-version文件，记录版本）
pyenv local 3.10.19
# 验证（仅在该目录下生效）
python --version # 输出Python 3.10.19
# 退出该目录后，恢复全局版本
cd ..
python --version # 输出全局版本（如3.11.9）
|
（3）临时版本（当前终端生效）
1
2
3
4
| # 仅当前终端会话使用3.10.19
pyenv shell 3.10.19
# 退出终端后失效
|
5. 卸载Python版本
1
| pyenv uninstall 3.11.9 # 卸载不需要的版本
|
五、实战用pyenv-win搭建SD环境
- 安装pyenv-win → 安装Python 3.10.19；
- 进入SD目录，执行
pyenv local 3.10.19； - 激活SD虚拟环境，安装依赖：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| # 进入SD目录
cd F:\stable-diffusion-webui
# 验证Python版本（确保是3.10.19）
python --version
# 创建/激活虚拟环境
python -m venv venv
venv\Scripts\activate
# 安装GPU版Torch（适配3.10.19）
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu121
# 启动SD
.\webui-user.bat
|
