梦行志Hermes Agent Python 虚拟环境排障：uv venv pip 不一致（Ubuntu 教程）
从 venv、.venv 到 pip 恢复正常——一次典型的 Python 虚拟环境路径混乱排障
Hermes Agent Python 虚拟环境排障：uv venv pip 不一致（Ubuntu 教程）
这篇文章记录我在 Ubuntu 上安装和修复 Hermes Agent 运行环境的完整过程。虚拟环境目录名、激活方式、pip 所在位置、以及 uv 对项目环境的默认处理方式——几件事叠在一起，表面看起来像是"环境坏了"，实际上只是"路径和命令没有统一"。
如果你也在 Linux 上部署 Hermes、Python 项目，或者在使用 uv 管理虚拟环境时遇到 “python 对了但 pip 不对” 的情况，这篇文章应该能帮你少走很多弯路。
一、最开始的目标
这次的目标其实很简单：在 Ubuntu 上把 Hermes Agent 配好，让它通过 LongCat API 跑起来，后面再作为整个 AI 数字工厂的策略中枢使用。
前面的基础工作都已经完成：
- 系统更新完成
- Python、Git、Node.js、构建工具都装好了
- Hermes Agent 也已经成功安装
- Hermes 的
config.yaml、.env、SOUL.md等配置也都配过
看起来一切都已经成了，真正的问题出现在运行环境层——也就是 Python 虚拟环境这一层。
二、问题是怎么暴露出来的
最开始我检查 Hermes 的运行环境时，发现一个非常奇怪的现象：
(venv) oklife@oklife-ub:~/.hermes/hermes-agent$ which python
/home/oklife/.hermes/hermes-agent/venv/bin/python
(venv) oklife@oklife-ub:~/.hermes/hermes-agent$ which pip
/usr/bin/pippython 指向的是 Hermes 自己的虚拟环境，但 pip 却还在指向系统环境。
更麻烦的是，python -m pip 甚至提示当前环境里没有 pip 模块：
(venv) oklife@oklife-ub:~/.hermes/hermes-agent$ python -m pip -V
/home/oklife/.hermes/hermes-agent/venv/bin/python: No module named pip这就很容易让人误判成"整个 Hermes 环境坏了"或者"系统 Python 被污染了"。其实不是，问题要更具体一点：虚拟环境本身存在，但里面没有完整的 pip 体系。
进一步检查后发现了三个叠加的根因：
- 虚拟环境目录名被我来回折腾过——有时叫
venv，有时叫.venv uv默认创建的是.venv，不是venv- 有一次激活错了路径，后续命令跑到了系统 Python 上，触发了 Debian/Ubuntu 的外部管理保护机制（PEP 668）
于是整个问题变成了一个非常典型的 “环境路径混乱” 问题。
三、最容易踩的坑：venv 和 .venv
这一点最值得单独说，因为它真的很容易绕死人。
在普通 python -m venv 的习惯里，很多人会默认创建一个叫 venv 的目录，然后用：
source venv/bin/activate但 uv 的默认行为不是这样。uv venv --python 3.11 默认会创建的是 .venv，并提示你用：
source .venv/bin/activate这就导致如果你脑子里默认想的是 venv，但实际工具创建的是 .venv，那后面的激活命令就会直接失效。
我中间就犯了这个错误：
# 我删掉了 venv
rm -rf venv
# uv 创建的是 .venv（不是 venv！）
uv venv --python 3.11
# 输出：Creating virtual environment at: .venv
# 但我以为还是 venv，执行了错误的激活命令
source venv/bin/activate
# bash: venv/bin/activate: 没有那个文件或目录这一步直接没激活成功，后面的所有命令都跑偏了。
四、为什么 ensurepip 把我带进了系统环境
当时为了补 pip，我尝试了 python -m ensurepip --upgrade 和 python -m pip install -U pip setuptools wheel。
结果很快就被 Ubuntu 的系统 Python 保护机制拦住了：
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install python3-xyz这说明什么？说明那一刻我实际上已经没有在虚拟环境里了，而是在系统 Python 上执行命令。
也就是说，问题不是 ensurepip 有问题，而是前面虚拟环境根本没激活对，导致后续所有包安装命令都被送到了系统 Python 上。
五、真正的关键发现：uv venv 默认不带 pip
后来我进一步确认，终于把核心问题找出来了：
uv venv 默认创建的虚拟环境里，未必自动带有 pip。
这才是最核心的点。
也就是说，哪怕你成功激活了 .venv，如果它内部没有 pip 模块，那么：
which python会是对的 ✅- 但
python -m pip会报No module named pip❌ pip -V也可能继续落回系统 pip ❌
这时候很多人会误以为"虚拟环境坏了"，其实不是，它只是没把 pip 预装进去。
六、正确的修复方式
当我把问题彻底看清楚后，修复方式就很明确了。
方案一：直接给当前环境补 pip（推荐）
在激活虚拟环境后执行：
uv pip install pip这一步会把 pip 装进当前 .venv 环境中。这其实是最直接、最省事的修法。
方案二：创建时就带上 seed
如果你想在创建环境时就顺手把 pip 带进去，可以用：
uv venv --seed --python 3.11这个方式更干净，后续就不用再额外补 pip。
七、最终修复过程
最后我采用了统一 .venv 的方式来整理这个环境。
整体过程如下：
# 1. 进入项目目录
cd ~/.hermes/hermes-agent
# 2. 清理旧环境（同时删掉 venv 和 .venv，避免混用）
rm -rf venv .venv
# 3. 用 uv 创建新环境（默认创建 .venv）
uv venv --python 3.11
# 4. 激活新环境
source .venv/bin/activate
# 5. 同步项目依赖（--active 确保在当前激活环境同步）
uv sync --active
# 6. 补装 pip（如果没带 --seed）
uv pip install pip然后验证：
which python
# /home/oklife/.hermes/hermes-agent/.venv/bin/python ✅
which pip
# /home/oklife/.hermes/hermes-agent/.venv/bin/pip ✅
python -m pip -V
# pip 26.1.1 from .../.venv/lib/python3.11/site-packages/pip (python 3.11) ✅
pip -V
# pip 25.1.1 from /usr/lib/python3/dist-packages/pip (python 3.14) ⚠️等等，最后一个 pip -V 还是显示系统 pip？
这里需要解释一下：pip -V 显示的是 shell 命令解析的结果。当你单独敲 pip 时，bash 可能优先匹配到了 /usr/bin/pip（系统路径在 PATH 中仍占有一席之地）。但这不影响你在虚拟环境里正常工作——which pip 和 python -m pip 都是对的，就说明环境没问题。
以后装包、查包、同步依赖，统一用这两种方式之一：
uv pip install <包名>
# 或者
python -m pip install <包名>不要再依赖裸的 pip 去判断环境是否正确，优先看 which pip 和 python -m pip -V。
最后确认 Hermes 正常：
hermes --version
# Hermes Agent v0.14.0 ✅八、这次修复里最重要的经验
这次最重要的教训，其实不是某一个命令，而是对整个环境的理解。
1. 先分清主体和运行环境
Hermes 本体的配置和数据，主要在：
~/.hermes/config.yaml~/.hermes/.env~/.hermes/sessions/~/.hermes/skills/~/.hermes/logs/
这些不属于 Python 虚拟环境。
而 .venv 或 venv 只是 Hermes 的 Python 运行层。删掉、重建、补包，影响的是运行环境，不是主体数据。
2. 不要同时维护多个环境名
venv 和 .venv 最好只保留一个。否则你会不断遇到：
- 激活错目录
- 命令落到系统 Python
pip指向不一致uv sync自己建新环境
最后把问题越弄越复杂。
3. 检查环境别只看提示符
终端前面的 (venv) 或 (hermes-agent) 不一定代表一切都对了。最可靠的判断永远是：
which python
which pip
python -m pip -V这三条一出，环境到底有没有对，立刻就能看出来。
4. 系统 Python 不要动
Ubuntu 这类系统现在越来越严格，系统 Python 往往受 PEP 668 限制。不要试图在系统 Python 里直接 pip install，否则很容易进入不可预期状态。
九、一句话总结
uv pip install pip——如果以后再遇到"虚拟环境里没有 pip"的问题，优先先试这条。
整个问题的本质就是：uv 默认创建的环境不带 pip，而我之前误以为它带了，导致激活和验证步骤全部错位。一旦理清了这个逻辑，修复就是一行命令的事。
参考来源
本文基于 2026 年 5 月 21 日实际操作的完整记录整理。