京公网安备11010502063487号升级到 Homebrew 的新 Python 或新版 Linux 发行版后,pip install 突然报 “error: externally-managed-environment” 是现在最常被搜索的 Python 报错之一。这篇在本机复现它,看清楚是什么拦住的、哪些命令被拦、各种绕过办法分别意味着什么(全程只用 --dry-run 和本地 wheel,没有真正安装任何东西)。
python3 -m pip install --dry-run demo-pkg -> 退出码 1
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
xyz, where xyz is the package you are trying to
install.
If you wish to install a Python library that isn't in Homebrew,
use a virtual environment:
python3 -m venv path/to/venv
source path/to/venv/bin/activate
python3 -m pip install xyz
If you wish to install a Python application that isn't in Homebrew,
it may be easiest to use 'pipx install xyz', which will manage a
virtual environment for you. You can install pipx with
brew install pipx
You may restore the old behavior of pip by passing
the '--break-system-packages' flag to pip, or by adding
'break-system-packages = true' to your pip.conf file. The latter
will permanently disable this error.
If you disable this error, we STRONGLY recommend that you additionally
pass the '--user' flag to pip, or set 'user = true' in your pip.conf
file. Failure to do this can result in a broken Homebrew installation.
Read more about this behavior here: <https://peps.python.org/pep-0668/>
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
拦住它的是标准库目录里的一个标记文件: <brew>/opt/python@3.15/Frameworks/Python.framework/Versions/3.15/lib/python3.15/EXTERNALLY-MANAGED(存在: True)
文件内容(前 6 行):
[externally-managed]
Error=To install Python packages system-wide, try brew install
xyz, where xyz is the package you are trying to
install.
If you wish to install a Python library that isn't in Homebrew,Homebrew 的 Python 在标准库目录放了 EXTERNALLY-MANAGED 文件,pip 看到它就拒绝修改这个环境,并打印文件里的建议。
pip install -> 被拦(externally-managed-environment);退出码 1;最后一行: hint: See PEP 668 for the detailed specification. pip install --user -> 被拦(externally-managed-environment);退出码 1;最后一行: hint: See PEP 668 for the detailed specification. pip install --target <目录> -> 放行;退出码 0;最后一行: Would install demo-pkg-1.0 pip install --prefix <目录> -> 放行;退出码 0;最后一行: Would install demo-pkg-1.0 pip install --break-system-packages -> 放行;退出码 0;最后一行: Would install demo-pkg-1.0 pip uninstall(一个没装的包) -> 被拦(externally-managed-environment);退出码 1;最后一行: hint: See PEP 668 for the detailed specification. pip list -> 放行;退出码 0;最后一行: pip 26.2.2 pip freeze -> 放行;退出码 0;最后一行: ndiff==7.992 pip download -> 放行;退出码 0;最后一行: Successfully downloaded demo-pkg pip show pip -> 放行;退出码 0;最后一行: Required-by:
会修改这个 Python 环境的命令被拦,包括 --user 和 uninstall;装到别的目录的 --target / --prefix 和只读命令不被拦。
python3 -m venv 创建耗时 1.90 s,占用磁盘 11.8 MB venv 里有没有标记文件: False venv 里 pip install --dry-run demo-pkg -> 退出码 0;['Would install demo-pkg-1.0'] venv 里的 pip: pip 26.2.2 from <tmp>/venv/lib/python3.15/site-packages/pip (python 3.15)
venv 里没有标记文件,pip 正常工作,创建成本只有几秒和十几 MB。
--break-system-packages --dry-run -> 退出码 0;['Would install demo-pkg-1.0'] 环境变量 PIP_BREAK_SYSTEM_PACKAGES=1 -> 退出码 0;['Would install demo-pkg-1.0'] 它会装到: <brew>/lib/python3.15/site-packages pipx 在这台机器上: True(本篇没有试用)
--break-system-packages 或环境变量能放行,但装进的是 Homebrew 管理的目录,标记文件警告可能弄坏 Homebrew 的安装。