3.11.0 API 变更#

行为变更#

pyplot.subplot 和 pyplot.subplot_mosaic 在现有图形上会抛出 ValueError#

向 subplots 或 subplot_mosaic 传递引用现有图形或为 Figure 实例的 num 参数，现在会抛出 ValueError。

这些辅助函数严格用于创建新的图形和子图。此前，由于它们在内部调用了 figure，因而不经意地允许了重用现有图形。此变更确保了这些函数严格遵循其文档中说明的创建新图形的目的。

若要重用现有图形，请先使用 clear=True 将其清除

fig, axs = plt.subplots(num=1, clear=True)
# or
fig, axd = plt.subplot_mosaic([['A', 'B']], num=1, clear=True)

如果您已有一个 Figure 实例并希望向其添加子图，请使用面向对象的 API

fig.subplots(nrows=2, ncols=2)
# or
fig.subplot_mosaic([['A', 'B']])

复杂布局和约束布局#

在某些情况下，约束布局（constrained layout）现在会在子图之间产生更小的间距。这应该只会影响行或列包含不同子图数量的复杂布局，例如使用 plt.subplot_mosaic('AC;BC', layout='constrained') 创建的布局。

双变量颜色映射现在完全覆盖预期的颜色范围#

由 SegmentedBivarColormap（例如 BiOrangeBlue）从一组输入颜色生成的双变量颜色映射现在可以完全覆盖该颜色范围。之前存在一个数值插值漏洞，导致颜色映射实际上并未包含第一种或最后一种颜色。

图像渲染现在更加精确#

进行了多项修复以提高渲染期间图像重采样和放置的准确性。之前的一些不精确处在输出中可能相差高达一个像素。最明显的改善是，现在数据像素与刻度线和网格线的对齐非常可靠。几乎所有的图像输出都发生了变化，但通常只是在定性上不明显的细微层面上。

图像上的 alpha 参数处理#

在 Matplotlib 3.10.1 之前，当向 imshow(..., alpha=...) 传递数组时，如果图像数据是 RGB 或 RGBA 图像，或者 rcParams["image.interpolation_stage"]（默认值：'auto'）解析为 "rgba"（原文此处拼写为 "rbga"），该参数会被静默忽略。

Matplotlib 3.10.1 将此行为更改为将 alpha 数组作为 alpha 通道应用，从而覆盖图像数据中任何现有的透明度信息。Matplotlib 3.11.0 进一步修复了 RGBA 图像的处理：现在的 alpha 通道会与 alpha 数组相乘，这与标量 alpha 值的处理方式一致。

plot 的图例标签#

以前，如果在绘制单个数据集时向 plot 的 label 参数传递了一个序列，该序列会自动转换为字符串作为图例标签。现在，如果序列长度不为 1，则会抛出错误。要保持旧行为，请在传递前将序列转换为字符串。

混合使用位置参数和关键字参数来指定 legend 的句柄和标签...#

...不再有效。如果向 legend 传递 handles 和 labels，现在必须全部作为位置参数传递，或全部作为关键字参数传递。

Axes.add_collection(..., autolim=True) 会更新视图限制#

Axes.add_collection(..., autolim=True) 到目前为止仅更新数据限制，还需要调用 Axes.autoscale_view 才能更新视图限制。现在，如果 autolim=True，视图限制也会被更新，这里采用了一种延迟内部更新机制，因此即使添加了多个集合，性能开销也只会有一次。

relim() 现在考虑了 Collection artist#

以前，relim 不会为 Collection artist（例如由 scatter 创建的 artist）重新计算数据限制。现在，调用 ax.relim() 后紧接着调用 ax.autoscale_view() 可以正确地将散点图和其他集合纳入坐标轴限制中。

hist2d 不再强制限制坐标轴范围#

以前，Axes.hist2d 会强制将坐标轴的 x 和 y 限制设置为直方图数据的范围，从而忽略任何其他 artist。现在，Axes.hist2d 的行为类似于 Axes.imshow：坐标轴限制会更新以适应数据，但自动缩放不会因此被禁用。

Axes.violinplot 和 cbook.violin_stats 忽略非有限值#

violinplot 和 matplotlib.cbook.violin_stats 现在会忽略掩码值和非有限值（NaN 和 inf）。

对数坐标轴次要刻度标签现由主要刻度数量决定，而非跨越的十倍频程数量#

以前，默认情况下，在对数刻度轴上，如果坐标轴限制跨越超过一个十倍频程，则不会标记次要刻度。现在，LogFormatter 的 minor_thresholds 参数含义已被修改，是否标记次要刻度的决定现在基于坐标轴范围内绘制的主要刻度的数量。

例如，对于范围从 4 到 60 的坐标轴（因此只有一个主要对数刻度，即 10），即使坐标轴跨越超过一个十倍频程，现在也会标记次要刻度。

使用 webagg 后端设置图形标题#

以前在使用 webagg 后端时，图形标题是使用 figure.set_label 设置的。现在，它改为使用 figure.canvas.manager.set_window_title 设置，这与其他后端更加一致。

ListedColormap 的默认名称#

ListedColormap 的默认名称已由 "from_list" 变更为 "unnamed"。

如果选定的字重与请求的字重不匹配，font_manager.findfont 会记录日志#

当搜索指定字重的字体时，如果最佳匹配字体的字重不一致，则会记录一条警告日志。

FT2Font 不再设置默认大小#

为了处理不可缩放字体并减少字体初始化开销，FT2Font 构造函数不再设置默认大小。不可缩放字体有时会用于基于位图的表情符号字体。

如果字形度量非常重要（例如，您正在加载字符字形，或者设置文本字符串），请在此之前显式调用 FT2Font.set_size。

mathtext.VectorParse 现在包含字形索引#

对于输出 path 的 MathTextParser，在 parse 的返回值（即一个 VectorParse）中，glyphs 字段现在是一个包含以下元组的列表：

具体来说，字形索引被添加在字符代码之后。

matplotlib.testing.check_figures_equal 默认仅检查 PNG#

在大多数情况下，使用 check_figures_equal 检查图形是否相等不依赖于文件格式。因此，extensions 参数现在的默认值变更为 ['png']，而不是 ['png', 'pdf', 'svg']，从而减少了默认的测试开销。

image_comparison 的默认 style 参数#

image_comparison 装饰器的 style 参数将在 Matplotlib 3.13 中变更为 'mpl20'。如果不进行传递而依赖之前的默认值，在发生变更前会触发警告。

Windows 配置目录位置#

在 Windows 上，默认配置和缓存目录现在使用 %LOCALAPPDATA%\matplotlib，而不是 %USERPROFILE%\.matplotlib。这符合 Windows 应用程序数据存储惯例。

仍可使用 MPLCONFIGDIR 环境变量来覆盖此默认设置。

弃用#

颜色映射的就地修改#

从长远来看，计划将颜色映射变为不可变对象。

作为第一步，现在对颜色映射的就地修改已被标记为待弃用。这会影响 Colormap 的以下方法：

请改为使用对应的 Colormap.with_extremes 和适当的关键字参数，这会返回颜色映射的副本（自 Matplotlib 3.4 起可用）。或者，如果您自行创建颜色映射，也可以直接将相应的参数传递给构造函数（自 Matplotlib 3.11 起可用）。

在填充等高线上标注标签#

已弃用使用 clabel 来标注由 contourf 创建的填充等高线。clabel() 旨在为等高线（Axes.contour）标注标签，在填充等高线上使用它可能会导致图表显示不一致。如果您想在填充等高线上添加标签，推荐的方法是先使用 contourf 创建填充等高线，然后使用 contour 叠加等高线，最后将 clabel 应用于这些等高线进行标注。示例请参见 Contourf demo。

boxplot 和 bxp 的 vert 参数，以及 rcParams["boxplot.vertical"]#

boxplot 和 bxp 中的 vert: bool 参数已被弃用。为了保持 API 的一致性，它已被替换为 orientation: {"vertical", "horizontal"}。

用于控制 boxplot 方向的 rcParams["boxplot.vertical"] 已被弃用，且没有替代方案。

violinplot 和 violin 的 vert 参数#

内建在 violinplot 和 violin 中的 vert: bool 参数已被弃用。为了保持 API 的一致性，它将被替换为 orientation: {"vertical", "horizontal"}。

axes.prop_cycle rcParam 字符串中的任意代码执行#

axes.prop_cycle rcParam 接受在受限上下文中求值的 Python 表达式。此求值上下文已进一步受到限制，一些以前可以工作的表达式（例如列表推导式）现在将不再能正常工作。为了提高安全性，该更改没有设置弃用过渡期。以前在 https://matplotlib.org.cn/cycler/ 中记录的 cycler 操作仍然受支持。

matplotlibrc 中 None 的大小写形式#

在 matplotlibrc 配置文件中，以前接受任意大小写形式的 None 来表示 Python 常量 None。这现在已被弃用，唯一接受的大小写形式是 None（即首字母大写，其他字母小写）。

第三方比例尺不再需要具有 axis 参数#

自 Matplotlib 3.1 的 PR 12831 以来，比例尺（scale）对象应该是可重用的，因此独立于任何特定的 Axis。因此，在 __init__ 中使用 axis 参数已经不再被推荐。然而，为了保持 API 的向后兼容性，在签名中保留该参数在当时仍是必要的。现在情况不再如此。

register_scale 现在接受带有或不带有该参数的比例尺类。

axis 参数属于待弃用状态。它将在 Matplotlib 3.13 中被正式弃用，并在 Matplotlib 3.15 中被移除。

如果第三方比例尺现在就能够将兼容性限制为 Matplotlib >= 3.11，则建议立即移除 axis 参数。否则，它们也可以保留 axis 参数，并在 Matplotlib 3.13 时及时将其移除。

matplotlib.style.core#

matplotlib.style.core 模块已被弃用。所有供公共使用的 API 现在都可以直接在 matplotlib.style 中使用（包括之前未被重新导出的 USER_LIBRARY_PATHS）。

matplotlib.style.core 的以下 API 已被弃用且没有替代方案：BASE_LIBRARY_PATH、STYLE_EXTENSION、STYLE_BLACKLIST、update_user_library、read_style_directory、update_nested_dict。

字体微调（hinting）和字距微调（kerning）系数#

由于支持复杂文本渲染的内部更改，字体上的微调系数（hinting factor）和字距微调系数（kerning factor）已不再使用。将 text.hinting_factor 或 text.kerning_factor rcParams（后者仅用于向后兼容）设置为除 None 之外的任何值均已被弃用，并将于未来移除。

同样地，向 FT2Font 构造函数传递 hinting_factor 参数已被弃用。

FT2Image 图像缓冲区#

请改用二维 uint8 ndarray。特别是：

  • FT2Image 构造函数将 width, height 作为独立的参数，但 ndarray 构造函数接收 (height, width) 单个元组参数。

  • FT2Font.draw_glyph_to_bitmap 现在（同样）接受二维 uint8 数组作为输入。

  • FT2Image.draw_rect_filled 应该通过直接将像素值设置为黑色来替换。

  • 由 MathTextParser("agg").parse 返回的对象的 image 属性现在是一个二维 uint8 数组。

DviFont.widths#

... 已弃用，无替代品。

PdfFile 内部机制#

PdfFile.dviFontInfo、PdfFile.fontNames、PdfFile.multi_byte_charprocs 和 PdfFile.type1Descriptors 属性已被弃用，且没有替代方案。

PdfFile.createType1Descriptor 的 fontfile 参数已被弃用；所有相关信息现在都直接从 t1font 参数中提取。

Tfm 的内部度量#

已弃用直接访问 Tfm 的 widths、heights、depths 字典；请改为使用 Tfm.get_metrics 访问字形的度量信息。

font_manager.is_opentype_cff_font 已被弃用#

没有替代方案。

Axes.set_navigate_mode 已被弃用#

... 无替代。

参数 Axes3D.set_aspect(..., anchor=..., share=...)#

Axes3D.set_aspect 的 anchor 和 share 参数已被弃用。它们对 3D 坐标轴没有影响，并将在未来版本中被移除。

BezierSegment.point_at_t#

...已被弃用。现在，可以直接传递参数来调用 BezierSegment。

格式化器属性#

以下属性被视为内部属性，用户不应该需要访问它们：

参数 ListedColormap(..., N=...)#

向 ListedColormap 传递 N 参数已被弃用。如有需要，请自行对颜色列表进行预处理。

QuiverKey 的 kw、fontproperties、labelcolor 和 verts 属性#

这些属性已被弃用（请注意，此前在首次绘制后修改 fontproperties、labelcolor 或 verts 是没有效果的）。请直接访问子 artist QuiverKey.vector 和 QuiverKey.text 上的相关属性。

PolarTransform 中的 apply_theta_transforms 选项#

在 PolarTransform 和 InvertedPolarTransform 中应用 theta 变换的功能已被移除，且 apply_theta_transforms 关键字参数在两个类中都已被弃用。

如果您需要保留对 theta 值进行变换的行为，请将 PolarTransform 与一个执行 theta 偏移和/或符号偏移的 Affine2D 变换进行级联。

RadialLocator 的 axes 参数#

...已被弃用。RadialLocator 现在将从 Axis 的父级 Axes 获取相关信息。

变换辅助函数#

以下函数在 transforms 模块中已被弃用，因为它们被视为内部功能，不应由最终用户使用：

  • matplotlib.transforms.nonsingular

  • matplotlib.transforms.interval_contains

  • matplotlib.transforms.interval_contains_open

InvertedSymmetricalLogTransform.invlinthresh#

InvertedSymmetricalLogTransform 的 invlinthresh 属性已被弃用。请改用 .inverted().transform(linthresh) 方法。

axisartist 现在使用更标准的刻度方向控制方式#

以前，axisartist 刻度的位置（在坐标轴内侧或外侧）是使用 set_tick_out(bool) 设置的。现在，它们改为使用 set_tick_direction("in")（或 "out" 或 "inout"）设置，并遵循 rcParams["xtick.direction"]（默认值：'out'）和 rcParams["ytick.direction"]（默认值：'out'）。特别是，它们现在默认朝外指向，与库中其他部分保持一致。

Ticks 的 tick_out 参数已被弃用（请改用 tick_direction）。Ticks.get_tick_out 方法已被弃用（请改用 Ticks.get_tick_direction）。

Ticks 和 LabelBase 未被使用的 locs_angles_labels 属性也已被弃用。

GridFinder.get_grid_info 现在接受单个 bbox 作为参数#

将 x1, y1, x2, y2 作为独立参数传递的方式已被弃用。

GridFinder.transform_xy 和 GridFinder.inv_transform_xy#

...已被弃用。请直接使用由 GridFinder.get_transform 返回的标准 transform。

axes_grid.Grid.ngrids#

该属性已被弃用并重命名为 n_axes，这与用于设置网格中实际坐标轴数量的 Grid 构造函数新参数名保持一致（旧参数 ngrids 自 Matplotlib 3.3 起实际上就无法正常工作）。

axes_grid.ImageGrid 中也进行了相同的更改。

MultiCursor 的 canvas 参数#

...已被弃用。它在之前的一段时间里就已经不再被使用了。

请移除该参数，并将调用方式从 MultiCursor(canvas, axes) 更改为 MultiCursor(axes)。在整个弃用过渡期内，两种调用方式都是有效的。

CallbackRegistry.disconnect 的 cid 参数重命名为 cid_or_func#

CallbackRegistry.disconnect 的 cid 参数已被重命名为 cid_or_func。该方法现在同样接受一个可调用对象（callable），从而断开该回调函数与所有信号的连接。如果提供了 signal 关键字参数，则断开与特定信号的连接。

cbook.normalize_kwargs 仅支持将 artist 和 artist 类作为第二个参数传递#

已弃用直接将别名映射或 None 作为第二个参数传递给 cbook.normalize_kwargs 的支持。

backend_svg.XMLWriter 已被弃用#

它是一个内部辅助工具，不供外部使用。

image.thumbnail#

...已被弃用，且没有替代方案。请改为使用 Pillow 的 thumbnail 方法。另请参见 Pillow 教程。

testing.widgets.mock_event 和 testing.widgets.do_event#

...已被弃用。请直接构建 Event 对象（通常为 MouseEvent 或 KeyEvent），并改将其传递给 canvas.callbacks.process()。

移除#

matplotlib.cm.get_cmap#

现在颜色映射可以通过由 matplotlib.colormaps 或 matplotlib.pyplot.colormaps 访问的 ColormapRegistry 来获取。

如果您拥有作为字符串的颜色映射名称，可以直接进行查找，如 matplotlib.colormaps[name] 或 matplotlib.pyplot.colormaps[name]。或者，matplotlib.colormaps.get_cmap 将保持现有行为，即额外允许直接传入 Colormap 实例，并将 None 转换为默认颜色映射。matplotlib.pyplot.get_cmap 将继续作为 matplotlib.colormaps.get_cmap 的快捷方式保留。

boxplot 刻度标签#

为了提高清晰度并与 bar 保持一致，labels 参数已被移除，取而代之的是 tick_labels。

plot_date#

自 Matplotlib 3.5 起不鼓励使用 plot_date，并且自 3.9 起已被弃用。现已将 plot_date 函数移除。

  • datetime 类型的数据应直接使用 plot 绘制。

  • 如果您需要将普通数值数据绘制为 Matplotlib 日期格式 或需要设置时区，请在 plot 之前调用 ax.xaxis.axis_date / ax.yaxis.axis_date。请参阅 Axis.axis_date。

GridHelperCurveLinear.get_tick_iterator#

...已被移除，没有替代方案。

针对固定坐标轴的 axisartist 辅助工具的 nth_coord 参数#

在直线坐标轴上生成“固定”轴的 axisartist 辅助 API（FixedAxisArtistHelperRectilinear）不再接受 nth_coord 参数。该参数完全从（必需的）loc 参数中推导得出。

对于曲线坐标轴，仍支持 nth_coord 参数（它影响 ticks 刻度，而不是坐标轴本身的位置），但它现在变更为仅限关键字参数。

rcsetup.interactive_bk、rcsetup.non_interactive_bk 和 rcsetup.all_backends#

...已被移除，并由具有以下参数的 matplotlib.backends.backend_registry.list_builtin 替代：

  • matplotlib.backends.BackendFilter.INTERACTIVE

  • matplotlib.backends.BackendFilter.NON_INTERACTIVE

  • None

TimerBase.start 的 interval 参数#

在启动定时器时不能再设置定时器间隔参数。取而代之的是，可以在定时器构造函数中指定该间隔，或者通过设置 timer.interval 属性来指定。

TransformNode.is_bbox#

...已被移除。请改为使用 isinstance(..., BboxBase) 对对象进行检查。

BboxTransformToMaxOnly#

...已被移除。它可以使用 BboxTransformTo(LockableBbox(bbox, x0=0, y0=0)) 来替代。

基于 toolmanager 的工具的图像路径语义#

此前，MEP22（“基于 toolmanager”）的工具会尝试相对于当前工作目录，或从 Matplotlib 自身的图像目录（作为备用方案）加载其图标（tool.image）。由于这两种方法对于第三方工具都存在问题（最终用户可能随时更改当前工作目录，且第三方无法在 Matplotlib 的图像目录中添加新图标），因此这一行为已被移除；取而代之的是，tool.image 现在会相对于定义了 Tool.image 类属性的源文件所在目录进行解析。（将 tool.image 定义为绝对路径同样有效，并与新旧语义均兼容。）

开发变更#

依赖项的最低支持版本提升#

对于 Matplotlib 3.11，最低支持版本已被提升

依赖项

mpl3.10 中的最低版本

mpl3.11 中的最低版本

Python

3.10

3.11

NumPy

1.23

1.25

pyparsing

2.3.1

3.0.0

这与我们的 依赖版本策略 以及 SPEC0 保持一致。

开发建议使用 pip 25.1#

开发（构建和测试）依赖项现在被指定为 依赖分组，而不是 单独的 requirements 文件。

因此，建议使用支持依赖分组的 pip 版本，即 25.1 或更高版本。请注意，如果您手动安装构建/测试依赖项（通过从 pyproject.toml 中复制列表），那么旧版本的 pip 就足够了。

字形索引现在与字符代码采用不同的类型表示#

以前，字符代码和字形索引的类型都是 int，这意味着您可能会错误地将它们混用。虽然字符代码不能被设置为独立的类型（因为它被用于 chr / ord），但将字形索引类型定义为独立类型意味着无法直接完全互换。

在此页