FIX: Deprecate using clabel() with filled contours

timhoffm · timhoffm · commit 169a730f7400 · 2026-03-23T03:30:52.000+01:00
It's never been intended to be used that way and may cause inconsistent plots. Closes #31344.
diff --git a/doc/api/next_api_changes/deprecations/31347-TH.rst b/doc/api/next_api_changes/deprecations/31347-TH.rst
@@ -0,0 +1,8 @@
+Contour labelling on filled contours
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using `~.Axes.clabel` to label filled contours created with `~.Axes.contourf` is deprecated. ``clabel()``
+is designed to label contour lines (`.Axes.contour`), and using it with filled contours can lead to inconsistent
+plots. If you want to add labels to filled contours, the recommended approach is to first create the filled contours
+with `~.Axes.contourf`, then overlay contour lines using `~.Axes.contour`, and finally apply `~.Axes.clabel` to those
+contour lines for labeling. For an example see :doc:`/gallery/images_contours_and_fields/contourf_demo`.
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -145,6 +145,17 @@ def clabel(self, levels=None, *,
             A list of `.Text` instances for the labels.
         """
 
+        if self.filled:
+            _api.warn_deprecated(
+                "3.11",
+                message="clabel() is not designed to be used with filled contours and "
+                        "may result in inconsistent plots. Applying clabel() to filled "
+                        "contours is thus deprecated since %(since)s. If you need "
+                        "labels with filled contours, instead draw contour lines "
+                        "using contour() in addition to contourf() and add the labels "
+                        "to the contour lines."
+            )
+
         # Based on the input arguments, clabel() adds a list of "label
         # specific" attributes to the ContourSet object.  These attributes are
         # all of the form label* and names should be fairly self explanatory.
diff --git a/lib/matplotlib/tests/test_contour.py b/lib/matplotlib/tests/test_contour.py
@@ -310,6 +310,15 @@ def test_label_contour_start():
     assert 0 in idxs
 
 
+def test_clabel_raises_on_filled_contours():
+    X, Y = np.meshgrid(np.arange(10), np.arange(10))
+    _, ax = plt.subplots()
+    cs = ax.contourf(X, Y, X + Y)
+    # will be an exception once the deprecation expires
+    with pytest.warns(mpl.MatplotlibDeprecationWarning):
+        ax.clabel(cs)
+
+
 @image_comparison(['contour_corner_mask_False.png', 'contour_corner_mask_True.png'],
                   remove_text=True, tol=1.88)
 def test_corner_mask():
@@ -359,21 +368,16 @@ def test_clabel_zorder(use_clabeltext, contour_zorder, clabel_zorder):
     x, y = np.meshgrid(np.arange(0, 10), np.arange(0, 10))
     z = np.max(np.dstack([abs(x), abs(y)]), 2)
 
-    fig, (ax1, ax2) = plt.subplots(ncols=2)
-    cs = ax1.contour(x, y, z, zorder=contour_zorder)
-    cs_filled = ax2.contourf(x, y, z, zorder=contour_zorder)
-    clabels1 = cs.clabel(zorder=clabel_zorder, use_clabeltext=use_clabeltext)
-    clabels2 = cs_filled.clabel(zorder=clabel_zorder,
-                                use_clabeltext=use_clabeltext)
+    fig, ax = plt.subplots()
+    cs = ax.contour(x, y, z, zorder=contour_zorder)
+    clabels = cs.clabel(zorder=clabel_zorder, use_clabeltext=use_clabeltext)
 
     if clabel_zorder is None:
         expected_clabel_zorder = 2+contour_zorder
     else:
         expected_clabel_zorder = clabel_zorder
 
-    for clabel in clabels1:
-        assert clabel.get_zorder() == expected_clabel_zorder
-    for clabel in clabels2:
+    for clabel in clabels:
         assert clabel.get_zorder() == expected_clabel_zorder
 
 
