在MacOS上通过Homebrew管理Python环境的最佳实践

问题描述

在 MacOS 上，通过 Homebrew 安装了 Python（路径为 /opt/homebrew/bin/python），同时系统中还安装了系统自带的 Python（路径为 /usr/bin/python3）。当尝试使用 pip 命令安装软件包（如 pip install opencv-python-headless）时，出现了以下错误信息：

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 non-brew-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-brew 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: 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.

问题分析

在 macOS 系统上，通常存在多个 Python 环境。系统自带的 Python 环境通常位于 /usr/bin/python3，而用户通过 Homebrew 安装的 Python 环境则位于 /opt/homebrew/bin/python。这些不同的 Python 安装路径有各自的用途：

• 系统级别的 Python 环境：通常用于操作系统自身的功能和系统工具。这个版本的 Python 是 macOS 操作系统的一部分，建议不要直接修改或在此环境中安装第三方软件包。
• Homebrew 安装的 Python 环境：通常用于用户的开发和安装第三方库。这个环境是用户可以自由控制的，适合用于开发和运行自定义的 Python 应用程序。

在 Homebrew 安装的 Python 环境中使用 pip 安装 Python 包时，出现了 externally-managed-environment 错误。这是因为 Homebrew 对其管理的 Python 环境实施了更加严格的保护措施，防止用户直接在全局环境中安装 Python 包，以避免可能导致系统不稳定的风险。根据 PEP 668，被标记为“externally managed”的 Python 环境不允许直接使用 pip 在全局范围内安装包。

解决方案

要解决这个问题，你可以选择以下几种方法：

1. 使用 Homebrew 安装 Python 包

如果你希望在系统范围内安装 Python 包，可以使用 Homebrew 安装。例如：

brew install opencv

这种方法确保了包的安装和系统管理的兼容性，而不会破坏 Homebrew 管理的 Python 环境。

2. 使用虚拟环境

创建一个虚拟环境来隔离你的开发环境，并在其中安装 Python 包。虚拟环境可以避免污染全局环境，并且是 Python 社区推荐的最佳实践：

/opt/homebrew/bin/python -m venv myenv
source myenv/bin/activate
pip install opencv-python-headless

在激活虚拟环境后，你可以自由地使用 pip 安装包，而不会受到系统级别的限制。

3. 使用 pipx

pipx 是一个专门用于安装和运行 Python 应用程序的工具。它会为每个应用程序创建一个独立的环境，防止与全局环境冲突：

pipx install opencv-python-headless

这种方法确保了每个应用程序的依赖关系都是独立的，不会影响其他项目或全局 Python 环境。

4. 强制安装

如果你确定要在当前 Homebrew 管理的 Python 环境中安装包，可以使用 --break-system-packages 选项来强制安装：

/opt/homebrew/bin/python -m pip install opencv-python-headless --break-system-packages

注意：这种方式有可能破坏 Homebrew 管理的 Python 环境，导致未来的维护和更新出现问题，需谨慎使用。

推荐做法

最安全且推荐的做法是创建并使用虚拟环境。通过这种方式，可以避免对系统和 Homebrew 管理的环境造成任何影响，同时能够灵活安装和管理第三方 Python 包。这种方法不仅可以隔离项目依赖，还可以更方便地管理和迁移项目环境。

我采用了使用虚拟环境的方法来解决这个问题：

/opt/homebrew/bin/python -m venv pyenv
source pyenv/bin/activate
pip install opencv-python-headless

pyenv是你自定义的名字，运行完第一条命令之后会在你运行命令时的当前目录下面创建一个名字为pyenv的目录，这里你也可以使用带路径的名字，这样你可以自定义保存这个虚拟环境目录到你想要保存的地方。执行完第二条命令后会在目录下多出一些文件出来，如下所示：

执行命令：

ls -l pyenv/bin

输出：

按照上面方法设置完虚拟环境之后，执行

which python
which pip

输出的路径不再是之前的路径了，而是指到当前的虚拟环境中。

总结

在 MacOS 上使用 Homebrew 安装 Python 后，通过 pip 安装包时可能会遇到“externally managed environment”错误。通过理解这个错误的原因并采取适当的解决方法，如使用虚拟环境或 pipx，可以避免对系统环境造成影响，同时确保开发环境的稳定性和可维护性。

---

本主页会定期更新，为了能够及时获得更新，敬请关注我：点击左下角的关注。也可以关注公众号：请在微信上搜索公众号“AI与编程之窗”并关注，或者扫描以下公众号二维码关注，以便在内容更新时直接向您推送。