pyenv 和 Python 环境怎么管理：版本切换、虚拟环境和项目收敛

Python 环境最容易乱在三个层面：系统 Python、项目 Python、包依赖。pyenv 解决的是 Python 解释器版本切换，不是依赖管理本身；虚拟环境或 uv 解决的是项目依赖隔离。把这两层分清，环境问题会少很多。

pyenv 适合解决什么

pyenv 的核心用途是让一台机器同时安装多个 Python 版本，并按全局、目录或当前 shell 切换。

常见命令：

pyenv install 3.12.4
pyenv versions
pyenv global 3.12.4
pyenv local 3.11.9
pyenv shell 3.10.14

global 是默认版本，local 会在当前目录写 .python-version，shell 只影响当前终端会话。

长期项目建议用 pyenv local 或直接在项目文档里写清 Python 版本，不要只靠个人机器的 global 设置。

虚拟环境解决依赖隔离

解释器版本确定后，还要处理依赖。两个项目都叫 requests，但版本可能不同；一个项目需要 Django 3，另一个需要 Django 5，不能混在全局 site-packages 里。

传统做法：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

更现代的个人项目可以用 uv 管理虚拟环境、依赖和锁文件：

uv init
uv add requests
uv run python main.py

pyenv 和 uv 并不冲突：pyenv 负责装 Python，uv 负责项目依赖和运行入口。

不要污染系统 Python

macOS 和 Linux 都可能自带 Python。系统 Python 经常被系统工具依赖，不建议随便升级、覆盖或全局安装大量包。

尽量避免：

sudo pip install xxx
pip install xxx

优先使用项目内 .venv、uv run 或临时工具的 uvx。这样卸载项目时，环境也可以一起清掉。

排查当前到底用的是哪个 Python

环境乱时，先跑几条命令：

which python
python --version
python -m site
pip --version

注意 pip 和 python 可能不是同一个环境。更稳的安装写法是：

python -m pip install package-name

这样至少能保证 pip 对应当前 python。

如果用了 pyenv，还要看：

pyenv version
pyenv which python

如果用了虚拟环境，看命令路径是否在项目 .venv/bin/python 下。

项目怎么收敛

一个可维护的 Python 项目至少要写清：

• Python 版本。
• 依赖管理方式：uv、venv + requirements.txt、Poetry 等。
• 启动命令。
• 测试命令。
• 是否需要本机私有配置。

对旧项目，可以先用 venv 跑起来，再逐步迁到 pyproject.toml 和锁文件。不要一边排线上问题，一边大换环境工具。

最后抓住一句话

pyenv 管 Python 版本，虚拟环境管项目依赖，uv 可以把依赖、运行和锁文件进一步收敛。排查时先确认 which python 和 python --version，再看依赖装到了哪里。