Ubuntu 系统无法通过 pip 命令安装 Python 库问题解决

为了更好的执行 Python 脚本，杜老师习惯使用 Ubuntu 系统，不过在安装 Python 库时经常报错。收集了安装 Python 库的报错信息，并整理了解决办法，供需要的小伙伴们参考。

问题提示

这里以上一篇《使用 Python 脚本实现图片相似度匹配》文中代码为例，首次执行时的报错信息如下：

penn@penn-VMware-Virtual-Platform:~/图片$ python3 1.py
Traceback (most recent call last):
  File "/home/penn/图片/1.py", line 4, in <module>
    import imagehash
ModuleNotFoundError: No module named 'imagehash'

根据报错信息，提醒找不到 imagehash 模块，使用 pip3 命令安装需要的模块，结果又出现了错误信息。这个信息表明正在尝试在一个由操作系统管理的 Python 环境中直接安装 Python 相关的包，为了保证系统 Python 环境的稳定性和安全性而采取限制措施：

penn@penn-VMware-Virtual-Platform:~/图片$ pip3 install imagehash
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.13/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 环境，同时方便管理依赖。按照提示创建一个虚拟环境，使用 python3 -m venv myenv 来创建虚拟环境，使用 source myenv/bin/activate 激活虚拟环境：

1 2	penn@penn-VMware-Virtual-Platform:~/图片$ python3 -m venv myenv penn@penn-VMware-Virtual-Platform:~/图片$ source myenv/bin/activate

在激活虚拟环境后，使用以下命令安装所需的包。安装完成后运行命令 deactivate，退出虚拟环境：

(myenv) penn@penn-VMware-Virtual-Platform:~/图片$ pip install imagehash
Collecting imagehash
  Downloading ImageHash-4.3.2-py2.py3-none-any.whl.metadata (8.4 kB)
Collecting PyWavelets (from imagehash)
  Downloading pywavelets-1.8.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (9.0 kB)
Collecting numpy (from imagehash)
  Downloading numpy-2.2.5-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (62 kB)
Collecting pillow (from imagehash)
  Downloading pillow-11.2.1-cp313-cp313-manylinux_2_28_x86_64.whl.metadata (8.9 kB)
Collecting scipy (from imagehash)
  Downloading scipy-1.15.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (61 kB)
Downloading ImageHash-4.3.2-py2.py3-none-any.whl (296 kB)
Downloading numpy-2.2.5-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (16.1 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 16.1/16.1 MB 21.3 MB/s eta 0:00:00
Downloading pillow-11.2.1-cp313-cp313-manylinux_2_28_x86_64.whl (4.6 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.6/4.6 MB 38.6 MB/s eta 0:00:00
Downloading pywavelets-1.8.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.5 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.5/4.5 MB 38.6 MB/s eta 0:00:00
Downloading scipy-1.15.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (37.3 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 37.3/37.3 MB 41.4 MB/s eta 0:00:00
Installing collected packages: pillow, numpy, scipy, PyWavelets, imagehash
Successfully installed PyWavelets-1.8.0 imagehash-4.3.2 numpy-2.2.5 pillow-11.2.1 scipy-1.15.2