Matplotlib导入失败求助：执行import matplotlib.pyplot as plt报错

问题重现 #

执行import matplotlib.pyplot as plt时触发以下错误：

Traceback (most recent call last):
  File "/home/<user>/Documents/vscode/python/scripts/script.py", line 1, in <module>
    import matplotlib.pyplot as plt
  File "/home/<user>/.local/lib/python3.10/site-packages/matplotlib/pyplot.py", line 66, in <module>
    from matplotlib.figure import Figure, FigureBase, figaspect
  File "/home/<user>/.local/lib/python3.10/site-packages/matplotlib/figure.py", line 43, in <module>
    from matplotlib import _blocking_input, backend_bases, _docstring, projections
  File "/home/<user>/.local/lib/python3.10/site-packages/matplotlib/projections/__init__.py", line 58, in <module>
    from mpl_toolkits.mplot3d import Axes3D
  File "/usr/lib/python3/dist-packages/mpl_toolkits/mplot3d/__init__.py", line 1, in <module>
    from .axes3d import Axes3D
  File "/usr/lib/python3/dist-packages/mpl_toolkits/mplot3d/axes3d.py", line 23, in <module>
    from matplotlib import _api, cbook, docstring, _preprocess_data
ImportError: cannot import name 'docstring' from 'matplotlib' (/home/mbayi/.local/lib/python3.10/site-packages/matplotlib/__init__.py)

问题原因 #

从错误路径可判断：

• 本地安装的新版Matplotlib位于~/.local/lib/python3.10/site-packages，已将docstring模块重命名为_docstring
• 系统自带的旧版mpl_toolkits.mplot3d位于/usr/lib/python3/dist-packages，仍尝试导入旧名称的模块，导致版本不兼容冲突

解决方案 #

方案1：统一依赖版本 #

卸载本地安装的Matplotlib，改用系统包管理器安装匹配版本：

1. 卸载本地Matplotlib：

pip uninstall matplotlib

2. 用系统包管理器安装适配版本（以Ubuntu/Debian为例）：

sudo apt install python3-matplotlib

方案2：使用虚拟环境隔离依赖 #

虚拟环境可完全隔离系统包与本地包，从根源避免版本冲突：

1. 创建虚拟环境：

python3 -m venv my_matplotlib_env

2. 激活虚拟环境：

source my_matplotlib_env/bin/activate

3. 在虚拟环境中安装Matplotlib：

pip install matplotlib

后续在该虚拟环境中运行代码即可解决问题。

内容的提问来源于stack exchange，提问作者j-leo7