摘要：问题描述：当我pip install xyz在 Linux 机器上运行时（使用 Debian 或 Ubuntu 或派生发行版），出现此错误：error: externally-managed-environment × This environment is externally managed ╰─>...

问题描述：

当我pip install xyz在 Linux 机器上运行时（使用 Debian 或 Ubuntu 或派生发行版），出现此错误：

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    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. Make
    sure you have python3-full installed.

    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.

    See /usr/share/doc/python3.11/README.venv for more information.

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.

这个错误是什么意思？我该如何避免？为什么pip install xyz它不能像我使用升级系统之前那样工作sudo apt upgrade？

解决方案 1：

安装 Python 库和应用程序的正确方法是尽可能将它们安装在 Python 虚拟环境中（此规则的例外情况非常罕见）。

错误消息描述了实现此目的的两种常用方法：自己创建虚拟环境，或者为应用程序使用pipx- 一个工具为您创建虚拟环境并在该虚拟环境中安装应用程序。

pipx强烈建议用于安装应用程序- 即当您主要从命令行使用已安装的代码时。在 Debian 系统和基于 Debian 的系统（如 Ubuntu）上，您可以pipx使用安装apt，然后使用pipx安装应用程序：

apt install pipx
pipx install some-python-application

对于库- 即当您主要通过在自己的项目中使用代码时- 通常您应该自己创建一个虚拟环境。您可以从标准库中import执行此操作：venv

python -m venv my-venv
my-venv/bin/pip install some-python-library

另请参阅重复问题上的这个答案以了解更多详细信息。

（通常，您自己的项目可能需要几个库。创建一个虚拟环境并在该虚拟环境中并排安装您的项目所需的库。）

如果您已仔细考虑过您的选择，但仍然确定要“全系统”安装软件包并冒着破坏系统的风险（例如，通过覆盖系统自带的用 Python 编写的工具的一部分库 - 如apt），Pip 需要获得这样做的权限。

有几种方法可以做到这一点：

对于 pip 的单独使用，请将--break-system-packages参数添加到命令中。
将这些行添加到~/.config/pip/pip.conf（这将使Pip将来的每次运行都破坏系统包）：

[global]
break-system-packages = true

使用 Pip 的config命令编辑上述文件（感谢评论中的The Matt ）：

python3 -m pip config set global.break-system-packages true

理论上，删除或重命名“标记”文件（/usr/lib/python3.x/EXTERNALLY-MANAGED）也会禁用该阻止，但这不是一个好主意 - 该文件放在那里是有原因的，至少使用预期的机制同样容易。

解决方案 2：

我从 Python 3.11+ 开始遇到此错误。

请考虑Alok和JackLeEmmerdeur在这篇文章中收到的相关评论：
This deletion of file is not safe. This can lead to Broken Package Management, Conflicting Installations and Permission Issues

因此，以下是更新后的答案，它允许我解决这个问题，而不会危及系统的风险：

sudo mv /usr/lib/python3.11/EXTERNALLY-MANAGED /usr/lib/python3.11/EXTERNALLY-MANAGED.old

解决方案 3：

该--break-system-packages标志pip允许覆盖externally-managed-environment错误并在整个系统内安装 Python 包。

pip install package_name --break-system-packages

注意：此标志的使用不应被滥用。

解决方案 4：

目前，一些得票最多的答案正在教你如何忽略这个问题。这就像告诉你吃止痛药来停止喉咙里碎玻璃的疼痛，而不是告诉你停止吃碎玻璃。别吃碎玻璃了。从 PyPI 安装软件包有很多比使用--break-system-packages标志或更糟糕的删除EXTERNALLY-MANAGED文件更好的方法。

该错误告诉您环境是外部管理的。您的 Debian 发行版已经使用 APT 处理 Python 库的安装。例如，如果您想安装requestsPython 库，您可以运行：

sudo apt install python3-requests

这些文件安装在中/usr/lib/python3/dist-packages/，您可以从命令的输出中看到dpkg -L：

$ dpkg -L python3-requests 
/usr/lib/python3/dist-packages/requests
/usr/lib/python3/dist-packages/requests/__init__.py
/usr/lib/python3/dist-packages/requests/__version__.py
/usr/lib/python3/dist-packages/requests/_internal_utils.py
# ...

如果运行pip install requests，文件应该安装在哪里？它们应该安装在/usr/lib/python3，还是~/.local/lib/python3/site-packages/或其他什么地方？使用 pip 从 PyPI 安装的版本可能与 Debian 包中包含的版本不同。如果覆盖不成功怎么办？如果requests系统范围内安装了两个包怎么办？pip 是否应该学习如何卸载 APT 包？您可能有数百个依赖于 Python 的 Debian 包，如果其中一个包因为这些冲突的版本而崩溃怎么办requests？您能轻松撤消pip安装吗？您是否会意识到启动时遇到的奇怪错误gedit或其他问题是由于这个造成的？这似乎是灾难的根源。您以前可以使用pip在系统范围内安装 Python 包，但这引起了很多问题，现在反而抛出了这个错误消息。

那么，你可以做什么呢？

使用 APT 安装软件包

您可以使用 APT 在系统范围内安装 Python 软件包。例如，您可以requests像这样安装：

sudo apt install python3-requests

此版本可能不是 PyPI 中最新的版本。而且 PyPI 上并非所有软件包都已打包到 Debian 存储库中。但不用担心，还有其他解决方案。

或者：2.`pip`在虚拟环境中使用

如果你还没有学会设置虚拟环境的工具，我强烈推荐它。所有 Python 程序员都应该学习一个。我向初学者推荐venv或。要安装，请运行：virtualenv`venv`

sudo apt install python3-venv

然后在你的项目目录中创建一个虚拟环境，如下所示：

 python3 -m venv .venv

现在通过运行以下命令激活您的虚拟环境：

 source .venv/bin/activate

这会将您的PATH环境变量修改为包含.venv/bin/。现在，您可以使用 pip 将 PyPI 包安装到您的虚拟环境（在本例中.venv/为）中，如下所示：

pip install requests

如果您不想激活和停用虚拟环境，您可以直接从虚拟环境运行pip和，如下所示：python

$ .venv/bin/pip install requests
$ .venv/bin/python
>>> import requests
>>>

或者：3.使用`pipx`

pipx是一款出色的工具，可直接从 PyPI 安装命令行应用程序。要安装pipx，请运行：

sudo apt install pipx

通过运行以下命令确保~/.local/bin/它在您的PATH环境变量中：

pipx ensurepath

关闭终端并再次打开以使更改生效。

现在您可以从 PyPI 安装命令行应用程序。在后台，pipx 将为每个应用程序及其依赖项设置一个虚拟环境，并与系统的其余部分完全隔离，以防止出现问题。这很棒。以下是一个例子：

$ pipx install ruff
$ ruff --help

或者：4.通过`--break-system-packages`

如果你一定要吃碎玻璃，那么你可以放弃这个--break-system-packages选项，就像这样：

pip install --break-system-packages requests

切勿删除或重命名/usr/lib/python3.12/EXTERNALLY-MANAGED。它的作用是防止您破坏系统。您可能直到几周或几个月后才注意到系统已损坏，并且那时您还不明白系统损坏的原因。如果您必须忽略这些保护措施，可以使用一次性执行此操作--break-system-packages。

解决方案 5：

只是

python3 -m venv ~/.local --system-site-packages

确保~/.local/bin在你的$PATH

然后使用

~/.local/bin/pip install ... # --user is implied ;)

您可能只需创建自己的~/py目录并从那里初始化所有内容。但是，我认为.local已被导入目录所采用PATH。

解决方案 6：

我首先安装了pipx ：

apt install pipx

然后我用来pipx安装radian：

pipx install radian

稍后为了确认安装位置（在我的情况下是配置Visual Studio Code），我运行了：

pipx list

解决方案 7：

在你的 shell (例如 bash) 中设置此环境变量：

export PIP_BREAK_SYSTEM_PACKAGES=1

或者将其写入你的Dockerfile中：

ENV PIP_BREAK_SYSTEM_PACKAGES 1

参考：Python 3.11、pip 和（破坏性的）系统包

解决方案 8：

# rm /usr/lib/python3.11/EXTERNALLY-MANAGED

解决方案 9：

使用：

打开终端
跑步sudo nano /etc/pip.conf
添加以下行：

[global]
break-system-packages = true

Ctrl+X然后Y→ 按（在nanoEnter编辑器中执行保存）

一切都已更新，现在您可以运行pip install <package_name>。

解决方案 10：

适用于所有 - Windows、Linux、MacOS、Android、PI 解决方案（将其放在 pip 命令末尾）：- --break-system-packages

pip install package-name --break-system-packages

解决方案 11：

Python 对于系统管理员来说就像地狱……不同的软件使用许多不同东西的不同版本。

有几次，我使用 pip3 来安装一些东西……这会破坏其他东西。有时我会将它与“apt-get install”混合使用。

这个错误信息就像天堂一样……因为它迫使我们做正确的事情。这意味着包管理器（Ubuntu、Debian）负责处理依赖关系，而不是pip。

这就是我们拥有Conda或Miniconda 的原因。

你可以使用类似的东西创建环境

conda create --name thenameofmyapp python=3.8

使用以下方式激活您的环境

conda activate pixray

然后您可以“pip install -r requirements.txt”它不会破坏您的系统:)它只会在特定环境中安装东西。

解决方案 12：

该问题来自 pip。只需运行该命令，它就会将其降级。

pip install pip==22.3.1 --break-system-packages

这肯定会有帮助。

解决方案 13：

就我而言，当我尝试安装mkdocs-material时发生了此错误，其解决方案是：

Linux/MAC：

$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ pip3 --version
pip 21.2.3 from .../python3.10/site-packages/pip (python 3.10)
(venv) $ pip --version
pip 21.2.3 from .../python3.10/site-packages/pip (python 3.10)

视窗：

C:> python -m venv venv
C:> venvScriptsactivate.bat
(venv) C:>  pip3 --version
pip 21.2.3 from ...libsite-packagespip (python 3.10)
(venv) C:>  pip --version
pip 21.2.3 from ...libsite-packagespip (python 3.10)

请阅读： https: //realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment

解决方案 14：

我正在尝试安装virtualenv并virtualenvwrapper使用全新的 Linux Mint 22 pip：

sudo pip3 install virtualenv
sudo pip3 install virtualenvwrapper

我得到了这个错误：

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    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. Make
    sure you have python3-full installed.
    
    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.
    
    See /usr/share/doc/python3.12/README.venv for more information.

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.

我按照它的建议做了：

要在系统范围内安装 Python 包，请尝试 apt install python3-xyz，其中 xyz 是您要安装的包。

因此这是有效的：

sudo apt install python3-virtualenv
sudo apt install python3-virtualenvwrapper

解决方案 15：

执行以下操作：

cd /usr/lib/python3.11

sudo rm EXTERNALLY-MANAGED

如果选择恢复此机制，请使用 touch 命令再次创建相同的文件：

sudo touch EXTERNALLY-MANAGED

解决方案 16：

要修复该错误，您可以使用 Python 虚拟环境。操作方法如下。

安装 Python 虚拟环境

然后，您可以进入所需的目录并使用创建虚拟环境virtualenv your_folder_name。在您创建的环境中，键入source bin/activate。

这是一个简单的方法（视频）。

那就这样了。

解决方案 17：

使用虚拟环境工作。

创建虚拟环境：

$ python3 -m venv ~/myVirtualEnv

访问虚拟环境目录：

$ cd ~/myVirtualEnv

激活（启动）此虚拟环境

$ source bin/activate

-> 你的 shell 会变成类似这样：

(myVirtualEnv) jose@nigriventer:~/myVirtualEnv$

如果您进入 myVirtualEnv，您可以直接运行 pip3 来安装包。当然，这些包将保持“锁定”在此虚拟环境中。

(myVirtualEnv) jose@nigriventer:~/myVirtualEnv$ pip3 install adafruit-ampy

解决方案 18：

尝试以下方法来避免外部管理env：

python3 -m venv path/to/venv.
source path/to/venv/bin/activate
python3 -m pip install xyz（任何扩展）

解决方案 19：

我在使用 Docker 镜像的管道作业上运行一些任务时遇到了这个问题。我以前没有遇到过这个问题，但由于我没有为 Docker 镜像使用任何特定标签，所以我也并不感到惊讶。

我正在运行以下命令：

python3 -m pip install --upgrade pip

我将其替换为：

python3 -m pip install --upgrade pip --break-system-packages

一切照常。

解决方案 20：

上下文：
我最终构建了一个具有 C++ 依赖项 (node-libcurl) 的 Node.js 映像，但我需要安装 python3，以便 node-gyp 为多种架构构建该 C++ 依赖项。我写这个答案是因为太多其他答案都采取了禁用警告的简单方法，这样你就有可能将问题推迟到以后再困扰你。

我的 Dockerfile 一直运行良好，直到最近构建的 python3 中 setuptools 不再明确包含在 apk 安装中。这个 Dockerfile 去年还在运行，但后来开始出现问题。它根本无法构建。node-gyp 包在 python3 中使用 gyp，但由于缺少 setuptools 包，gyp 根本就不存在。

ARG NODE_TAG=20-alpine
ARG PLATFORM_ARCH=linux/amd64

FROM --platform=${PLATFORM_ARCH} node:${NODE_TAG} as devBuild

WORKDIR /home

# ------------------
# dev dependencies
# ------------------
# node-libcurl build from source (works on x64 / arm64 as of Oct 2023)
RUN apk add --update --no-cache libcurl python3 alpine-sdk curl-dev \n  && npm install node-libcurl --build-from-source \n  && rm -rf /var/cache/apk/*dil
# ----------------

COPY package.json ./
COPY yarn.lock ./
RUN yarn install

# ... and so on

根据这个 SO 答案，我可以看到获取 setuptools 是解决方案。所以我尝试了 python3 -m pip install setuptools：

# ------------------
# dev dependencies
# ------------------
# node-libcurl build from source (works on x64 / arm64 as of Oct 2023)
RUN apk add --update --no-cache libcurl python3 alpine-sdk curl-dev \n  && python3 -m pip install setuptools \n  && npm install node-libcurl --build-from-source \n  && rm -rf /var/cache/apk/*dil
# ----------------

但它不起作用，我收到了上述关于“外部管理环境”的消息，这让我来到这里。

此消息建议我使用 apk 安装 setuptools，因为 python3 由该工具控制。所以我终于意识到（感谢此处其他答案的提示）我应该在 dev 依赖项部分添加 py3-setuptools：

# ------------------
# dev dependencies
# ------------------
# node-libcurl build from source (works on x64 / arm64 as of Oct 2023)
RUN apk add --update --no-cache libcurl python3 py3-setuptools alpine-sdk curl-dev \n  && npm install node-libcurl --build-from-source \n  && rm -rf /var/cache/apk/*dil
# ----------------

现在我可以再次为 x64 和 arm 架构构建基于 Node 的 Docker 映像了！

解决方案 21：

当我尝试在 Debian/Ubuntu 上设置 Ansible 时弹出此错误，下面是对我有用的解决方案的简化答案：

# Install venv if you don't have already. 
# Folder here .venv for me, but can be anything you choose
python3 -m venv .venv

# Now, lets use that virtual environment to install Ansible (or any package of your choice)
.venv/bin/pip3 install ansible

# Let's activate the virtual environment
source .venv/bin/activate

# Quick test, and congratulations! You got Ansible now! :-)
ansible --version

感谢其他人的回答。抱歉，pipx对我来说不太管用，而且venv确实管用，必须承认我可能有偏见，venv因为我经常使用它）。也不想启用该--break-system-packages选项。

我的评论只是为了分享我的经验，并简化快速的行动过程。

解决方案 22：

安装发行版包管理器中不可用的包的另一种方法可能是使用 pip 的前缀选项，如packaging.python.org中所述

pip install --prefix=/some/path
调用 sysconfig.get_preferred_scheme('prefix')。

前缀取决于发行版。例如，Debian使用/usr/local来存放未通过系统包管理器安装的包。

也可能存在一些陷阱。在Devuan上（因此可能在 Debian 本身和其他衍生产品上也是如此），定位/usr/local所需的前缀是/usr：

pip install --prefix=/usr some_package

将some_package安装在/usr/local中，以便系统包管理器安装的应用程序可以看到它。

然而，

pip install --prefix=/usr/local some_package

在/usr/local/local中安装some_package，但是不起作用。

解决方案 23：

我在尝试在 python 3.12 的虚拟环境中使用 pip 时遇到了这个问题。

可能需要一些防护栏来避免错误地在系统范围的 python 上安装包（对于从未这样做过的人，先扔石头吧）。

因此在加载 venv 后

source venv/bin/activate

你应该pip通过指向 venv 目录或使用带有模块标志的激活的 python来使用你的

./venv/bin/pip install xyz
# or
python3 -m pip install xyz

解决方案 24：

另一个没人提到的选项是从源代码安装！不需要 pip 或虚拟环境。只需下载源代码和python setup.py install。我发现这是最好和最省事的方法，尤其是我使用了许多未提供的模块apt。此外，这种方法与配合得很好Dockerfile。

解决方案 25：

我不确定作者的环境以及他们尝试安装哪个包，但也许这会对其他人有所帮助。

我在使用Visual Studio Code的 Python 扩展时遇到了这个错误。它需要在WSL中安装Pylint，当我尝试执行此操作时，我遇到了同样的错误。可以通过使用APT安装 Pylint 来解决这个问题：

sudo apt install python3-pylint-common

解决方案 26：

看一下这个。它无需在 Bash 中使用 venv 即可修复此问题：

在 Mac 上打开终端，并确保你的 shell 是 Bash
类型nano ~/.bash_profile
使用箭头键转到底部bash_profile
粘贴export PATH=".:/Library/Frameworks/Python.framework/Versions/3.12/bin:/usr/local/bin:${PATH}"到底部bash_profile
输入Control+ X，按Y，然后Enter
类型source ~/.bash_profile
享受！

解决方案 27：

如果你使用venv并且仍然收到此错误，请尝试

pip cache purge

解决方案 28：

我在尝试安装图像时遇到了它numpy。google/cloud-sdk docker例如：

$ docker run --rm -it google/cloud-sdk:477.0.0-alpine
/ # apk add py3-pip
/ # pip install numpy
<the externally managed message>

为了克服这个问题我做了：

$ docker run --rm -it google/cloud-sdk:477.0.0-alpine
/ # apk add py3-pip
/ # python -m venv env
/ # env/bin/pip install numpy
/ # export PYTHONPATH=/env/lib/python3.11/site-packages

PYTHONPATH将安装包的目录/env/bin/pip（/env/lib/python3.11/site-packages）添加到搜索路径。

从gcloud compute ssh INSTANCE输出结果来看，它确实起作用了。如果没有numpy它，则显示：

警告：
为了提高隧道的性能，请考虑安装 NumPy。有关说明，请参阅https://cloud.google.com/iap/docs/using-tcp-forwarding#increasing_the_tcp_upload_bandwidth

或者用另一种方式来确认：

/ # python -c 'import numpy'

您可以在以下要点中找到生成的图像。

解决方案 29：

如果您处于虚拟环境中（建议这样做），
sudo pip install.... 将导致“外部管理”错误。由于“sudo”表示系统范围的安装，因此这似乎是合乎逻辑的结果。

几个小时前我遇到了这个问题，几年前在一个项目上工作时习惯使用“sudo”。

pip install ...

在虚拟环境中这样做是正确的。

希望这能帮助那些和我一样经验不足的人。

解决方案 30：

OP 没有说明错误是否发生在虚拟环境中。我见过的大多数答案都假设不会发生。我提供了有关 此错误何时发生在虚拟环境中的答案。

在虚拟环境中，导致此错误最可能的原因是 venv 文件夹已重命名或移动。令人惊讶的是，这是不允许的。原因是所有脚本bin以及都使用绝对路径。安全且推荐的操作是重新创建一个新的 venv 作为已停用的 venv 的副本。但是，可以通过更正所有路径来“修复”重命名/移动的虚拟环境。这里有一个对我有用的pyvenv.cfg单行代码sed

cd <your_new_virtual_environment>
sed -i s'/<OLDPATH>/<NEWPATH>/g' pyvenv.cfg bin/*

/记住以/诸如此类的方式逃脱。

每次使用 pip 3 时，如何解决“错误：外部管理环境”？

问题描述：

解决方案 1：

解决方案 2：

解决方案 3：

解决方案 4：

使用 APT 安装软件包

或者：2.`pip`在虚拟环境中使用

或者：3.使用`pipx`

或者：4.通过`--break-system-packages`

解决方案 5：

解决方案 6：

解决方案 7：

解决方案 8：

解决方案 9：

解决方案 10：

解决方案 11：

解决方案 12：

解决方案 13：

解决方案 14：

解决方案 15：

解决方案 16：

安装 Python 虚拟环境

解决方案 17：

解决方案 18：

解决方案 19：

解决方案 20：

解决方案 21：

解决方案 22：

解决方案 23：

解决方案 24：

解决方案 25：

解决方案 26：

解决方案 27：

解决方案 28：

解决方案 29：

解决方案 30：

云端的项目管理软件

问题描述：

解决方案 1：

解决方案 2：

解决方案 3：

解决方案 4：

使用 APT 安装软件包

或者：2.pip在虚拟环境中使用

或者：3.使用pipx

或者：4.通过--break-system-packages

解决方案 5：

解决方案 6：

解决方案 7：

解决方案 8：

解决方案 9：

解决方案 10：

解决方案 11：

解决方案 12：

解决方案 13：

解决方案 14：

解决方案 15：

解决方案 16：

安装 Python 虚拟环境

解决方案 17：

解决方案 18：

解决方案 19：

解决方案 20：

解决方案 21：

解决方案 22：

解决方案 23：

解决方案 24：

解决方案 25：

解决方案 26：

解决方案 27：

解决方案 28：

解决方案 29：

解决方案 30：

云端的项目管理软件

或者：2.`pip`在虚拟环境中使用

或者：3.使用`pipx`

或者：4.通过`--break-system-packages`