从 "externally-managed-environment" 到 vLLM 跑通大模型：一份 WSL2 实战记录

如果你最近在 WSL2 的 Ubuntu 里用 pip 装东西，大概率撞上过这个报错：

code复制error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, first. Make sure you have python3-full installed.

我第一次在 Ubuntu 22.04 的 WSL2 里装 PyTorch 时，看到这串字整个人都愣了——我之前在别的机器上 pip install 从来没遇到过这个拦截。后来才搞清楚，这不是环境坏了，也不是权限不够，而是 Python 包管理的一次规则升级。这篇文章就把我从这个报错开始，到最终在 WSL2 里跑通 PyTorch + vLLM 的完整过程记录下来，包括每一步的踩坑和排查思路，希望能帮后来的人少走几趟弯路。

先说结论：这个问题不解决，PyTorch、vLLM 这些重量级 Python 包根本装不进去；解决方式有很多，但选错方案后面会踩更大的坑。适合刚接触 Ubuntu/WSL2、或者被这个报错拦住的开发者参考。

1. 报错背后是谁在管你的 Python 环境

1.1 错误的完整样貌

除了上面那段，完整的报错还会带一段提示：

code复制error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, first. Make sure you have python3-full installed.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    Note: In this environment, this is not a problem!

注意最后那行 "Note: In this environment, this is not a problem!"，这不是系统在说废话，而是在明确告诉你：这不是错误，是策略。系统故意不让你直接往全局环境里装包。

1.2 系统如何判断"外部管理"：EXTERNALLY-MANAGED 标记

这个机制来自 Python 的 PEP 668，全称是 "Marking Python base environments as externally managed"。它的做法很简单：在 Python 安装目录下放一个标记文件，通常路径是 /usr/lib/python3.11/EXTERNALLY-MANAGED，文件内容类似于：

code复制[externally-managed]
Error=To install Python packages system-wide, try apt install python3-xyz, first...

pip 在安装时会检测这个文件，如果存在就直接拒绝在全局环境安装，除非你显式加了 --break-system-packages 参数。

这套机制的初衷非常好理解：操作系统自带的 Python 是给 apt 和系统工具用的。如果你用 pip 往里面塞了一堆新版本包，很可能把系统依赖搞崩——比如某个包的新版本和 apt 里某个工具要求的旧版本冲突，可能导致系统级的功能直接挂掉。这就像宿舍的公共厨房，你用完了不收拾，还把自己买的冰箱推进去占了公共空间，后来的人就没法做饭了。

1.3 为什么 Ubuntu 22.04 也可能撞上

严格来说，Ubuntu 22.04 自带的 Python 3.10 默认没有启用 PEP 668 拦截，这个机制是从 Ubuntu 23.04 和 Debian 12 开始默认开启的。但实际使用中，我见过很多在 Ubuntu 22.04 上遇到这个报错的情况，主要分两种：

第一种，你自己装了更高版本的 Python。比如用源码编译安装了 Python 3.11/3.12，或者用了 deadsnakes PPA。这些新版本 Python 默认会带 EXTERNALLY-MANAGED 标记。

第二种，你用的不是原版 Ubuntu 22.04，而是基于它的发行版，或者你在 Docker 里用了更新的 Debian 基础镜像。

另外，不少教程会引导你升级 Python 版本或者用 pyenv 管理多版本，这些情况下撞上 PEP 668 几乎是必然的。

2. 三条出路：选错方案会付出额外代价

2.1 venv：官方推荐，也是我的默认选择

PEP 668 报错信息里其实已经把解决方案写得很清楚了——用虚拟环境。这也是我最终采用的方案。

创建一个虚拟环境非常简单：

code复制