安装#

安装官方版本#

Matplotlib 的版本可在 PyPI 上以 macOS、Windows 和 Linux 的 wheel 包形式获取。使用 pip 进行安装

python -m pip install -U pip
python -m pip install -U matplotlib

如果此命令导致 Matplotlib 从源代码编译，并且编译出现问题，你可以添加 --prefer-binary 以选择适用于你的操作系统和 Python 的最新预编译 wheel 包版本的 Matplotlib。

注意

以下后端开箱即用：Agg、ps、pdf、svg

Python 通常附带 TkAgg 使用的 tk 绑定。值得注意的是，python-build-standalone（uv 所用）不包含 Matplotlib 可用的 tk 绑定。

为了支持其他 GUI 框架、LaTeX 渲染、保存动画以及更多文件格式选择，你可以安装可选依赖项。

第三方发行版#

各种第三方为其环境提供 Matplotlib。

Conda 包#

Matplotlib 既可通过 anaconda 主频道获取

conda install matplotlib

也可通过 conda-forge 社区频道获取

conda install -c conda-forge matplotlib

Python 发行版#

Matplotlib 是主要 Python 发行版的一部分

Linux 包管理器#

如果你使用的是 Linux 发行版自带的 Python 版本，你可以通过你的包管理器安装 Matplotlib，例如：

  • Debian / Ubuntu: sudo apt-get install python3-matplotlib

  • Fedora: sudo dnf install python3-matplotlib

  • Red Hat: sudo yum install python3-matplotlib

  • Arch: sudo pacman -S python-matplotlib

安装每夜构建版本#

Matplotlib 在 scientific-python-nightly-wheels Anaconda Cloud 组织上提供每夜开发构建的 wheel 包。可以通过将 scientific-python-nightly-wheels 指定为查询的包索引，使用 pip 安装这些 wheel 包

python -m pip install \
  --upgrade \
  --pre \
  --index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
  --extra-index-url https://pypi.ac.cn/simple \
  matplotlib

从源代码安装#

为开发目的安装

如果你想为 Matplotlib 贡献代码或需要安装最新的开发代码，请遵循设置 Matplotlib 以供开发中的说明。

以下说明是关于为生产用途从源代码安装的。这通常不推荐；请尽可能使用预构建的包。请谨慎操作，因为这些说明可能导致你的构建产生意外行为和/或导致本地测试失败。

在尝试安装 Matplotlib 之前，请安装依赖项。

要从 tarball 构建，请从 PyPI 文件页面下载最新的 tar.gz 发布文件。

如果你在 Windows 上构建自己的 Matplotlib wheel 包（或 sdists），请注意你复制到源代码树中的任何 DLL 也将被打包。

配置构建和行为默认值#

我们提供了一个 meson.options 文件，其中包含可用于自定义构建过程的选项。例如，使用哪个默认后端，Matplotlib 附带的一些可选库是否已安装等等。这些选项对于打包 Matplotlib 的人来说尤其有用。

库的一些行为默认值可以通过以下方式配置：

默认绘图外观和行为可以通过 rcParams 文件进行配置

依赖项#

如果你使用 pip 或 conda 等包管理器安装 Matplotlib，强制依赖项应自动安装；因此此列表主要用于参考和故障排除。

常见问题#

报告编译问题#

请参阅获取帮助。

Matplotlib 编译成功，但使用时没有显示任何内容#

首先尝试进行全新安装，看看是否有帮助。如果没有，测试安装的最佳方法是运行脚本，而不是从 Python shell 或 IDLE 等集成开发环境进行交互式操作，因为这些会增加额外的复杂性。打开 UNIX shell 或 DOS 命令提示符并运行，例如

python -c "from pylab import *; set_loglevel('debug'); plot(); show()"

这将为你提供关于 Matplotlib 加载了哪些后端、版本信息等额外信息。此时，你可能需要确保你理解 Matplotlib 的配置过程，该过程由包含指令的 matplotlibrc 配置文件和 Matplotlib 后端的概念所控制。

如果你仍然遇到问题，请参阅获取帮助。

如何完全删除 Matplotlib#

有时，通过全新安装包可以解决 Matplotlib 的问题。要完全删除已安装的 Matplotlib，请执行以下操作：

  1. 从你的Matplotlib 配置目录中删除缓存。

  2. 从你的安装目录中删除任何 Matplotlib 目录或 egg 文件。

macOS 注意事项#

macOS 应该使用哪个 Python？#

Apple 在 macOS 中附带了自己的 Python（位于 /usr/bin/python）以及 Matplotlib 的副本。不幸的是，Apple 当前安装 NumPy、Scipy 和 Matplotlib 副本的方式意味着这些包难以升级（参见系统 Python 包）。因此，我们强烈建议你安装一个全新的 Python 版本，并以此作为安装 NumPy 和 Matplotlib 等库的基础。一种方便的方法是使用 Anaconda Python 科学软件集合来安装 Matplotlib 和其他有用的 Python 软件，该集合包含 Python 本身和各种库；如果你需要集合中没有的库，可以使用 pip 等标准方法自行安装。请参阅 Anaconda 网页以获取安装支持。

全新安装 Python 的其他选项包括从 python.org 获取的标准安装程序，或者使用 macOS 通用包管理系统（如 homebrew 或 macports）安装 Python。macOS 上的高级用户可能希望在他们的系统上使用 homebrew 或 macports 来安装开源软件包，但完全可以使用这些系统与另一个 Python 二进制文件来源（例如 Anaconda 或 Python.org Python）结合使用。

安装 macOS 二进制 wheel 包#

如果你使用的是来自 https://pythonlang.cn、Homebrew 或 Macports 的 Python，那么你可以使用标准的 pip 安装程序以 wheel 包的形式安装 Matplotlib 二进制文件。

pip 默认随 python.org 和 Homebrew Python 安装，但在 Macports 上需要手动安装，命令如下：

sudo port install py38-pip

安装 pip 后，你可以从 Terminal.app 命令行安装 Matplotlib 及其所有依赖项

python3 -m pip install matplotlib

你可能还想安装 IPython 或 Jupyter notebook（python3 -m pip install ipython notebook）。

检查你的安装#

新版本的 Matplotlib 现在应该在你的 Python “路径”中。在 Terminal.app 命令行中检查此项

python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)'

你应该会看到类似如下内容：

3.10.0 /Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/matplotlib/__init__.py

其中 3.10.0 是你刚刚安装的 Matplotlib 版本，后面的路径取决于你使用的是 Python.org Python、Homebrew 还是 Macports。如果你看到其他版本，或者收到类似以下错误：

Traceback (most recent call last):
  File "<string>", line 1, in <module>
ImportError: No module named matplotlib

那么通过运行以下命令检查 Python 二进制文件是否是你预期的那一个：

which python3

如果你得到类似 /usr/bin/python... 的结果，那么你使用的是 macOS 自带的 Python，这可能不是你想要的。在再次运行检查之前，请尝试关闭并重新启动 Terminal.app。如果这不能解决问题，根据你想使用的 Python 版本，考虑重新安装 Python.org Python，或检查你的 Homebrew 或 Macports 设置。请记住，磁盘映像安装程序仅适用于 Python.org Python，并且不会被其他 Python 版本识别。如果所有这些都失败了，请告知我们。

故障排除#

获取 Matplotlib 版本#

要查找你的 Matplotlib 版本号，请导入它并打印 __version__ 属性

>>> import matplotlib
>>> matplotlib.__version__
'0.98.0'

matplotlib 安装位置#

你可以通过导入 Matplotlib 并打印 __file__ 属性来查找 Matplotlib 的安装目录

>>> import matplotlib
>>> matplotlib.__file__
'/home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/__init__.pyc'

matplotlib 配置和缓存目录位置#

每个用户都有一个 Matplotlib 配置目录，其中可能包含一个 matplotlibrc 文件。要找到你的 matplotlib/ 配置目录，请使用 matplotlib.get_configdir()

>>> import matplotlib as mpl
>>> mpl.get_configdir()
'/home/darren/.config/matplotlib'

在类 Unix 系统上，此目录通常位于你的 HOME 目录下的 .config/ 目录中。

此外，用户还有一个缓存目录。在类 Unix 系统上，默认情况下此目录与配置目录是分开的。要找到你的 .cache/ 目录，请使用 matplotlib.get_cachedir()

>>> import matplotlib as mpl
>>> mpl.get_cachedir()
'/home/darren/.cache/matplotlib'

在 Windows 上，配置目录和缓存目录默认相同，并且位于你的 Documents and Settings 或 Users 目录下

>>> import matplotlib as mpl
>>> mpl.get_configdir()
'C:\\Documents and Settings\\jdhunter\\.matplotlib'
>>> mpl.get_cachedir()
'C:\\Documents and Settings\\jdhunter\\.matplotlib'

如果你想使用不同的配置目录，可以通过在 MPLCONFIGDIR 环境变量中指定位置来做到这一点——请参阅在 Linux 和 macOS 中设置环境变量。请注意，MPLCONFIGDIR 会设置配置目录和缓存目录的位置。

在此页