matplotlib · AdityaJagtap18 · Sep 6, 2026 · Sep 7, 2026
diff --git a/doc/api/next_api_changes/behavior/hist2d_unit_conversion.rst b/doc/api/next_api_changes/behavior/hist2d_unit_conversion.rst
@@ -0,0 +1,11 @@
+``Axes.hist2d`` now converts *x*/*y*/*range* through the axis unit converters
+------------------------------------------------------------------------------
+
+`~matplotlib.axes.Axes.hist2d` previously passed *x* and *y* directly to
+`numpy.histogram2d` without applying the axes' unit converters, unlike
+`~.Axes.plot`, `~.Axes.scatter`, and `~.Axes.hist`. This meant that, e.g.,
+plotting ``datetime64`` data with `~.Axes.hist2d` produced bin edges in raw
+(often nanosecond-scale) units instead of Matplotlib's internal date
+representation, so the histogram did not line up with other artists plotted
+on the same Axes. ``x``, ``y``, and ``range`` (if passed) are now converted
+consistently with the other plotting methods.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -7992,8 +7992,20 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
            Previously, `~.Axes.hist2d` would force the axes limits to match the
            extents of the histogram; now, autoscaling also takes other plot
            elements into account.
+
+        .. versionchanged:: 3.12
+           *x* and *y* (and *range*, if given) are now passed through the axes'
+           unit converters before binning, so e.g. datetime inputs are handled
+           the same way as in `~.Axes.plot` and `~.Axes.scatter`. Previously
+           they were passed unconverted to `numpy.histogram2d`.
         """
 
+        x, y = self._process_unit_info([("x", x), ("y", y)], kwargs)
+        if range is not None:
+            (xmin, xmax), (ymin, ymax) = range
+            range = (self.convert_xunits((xmin, xmax)),
+                     self.convert_yunits((ymin, ymax)))
+
         h, xedges, yedges = np.histogram2d(x, y, bins=bins, range=range,
                                            density=density, weights=weights)
 

diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -2919,6 +2919,37 @@ def test_hist2d_autolimits():
     assert ax.get_autoscale_on()  # Autolimits have not been disabled.
 
 
+def test_hist2d_datetime():
+    # Regression test for gh-17319: hist2d must apply the same unit
+    # conversion to x/y as plot()/scatter() so datetime input lands on the
+    # same (small, date2num-like) numeric scale, instead of raw
+    # nanosecond-scale datetime64 integers.
+    x = np.arange(np.datetime64('2020-01-01'), np.datetime64('2020-01-11'))
+    y = np.arange(10.)
+
+    ax_hist2d = plt.figure().add_subplot()
+    ax_hist2d.hist2d(x, y, bins=5)
+
+    ax_plot = plt.figure().add_subplot()
+    ax_plot.plot(x, y)
+
+    assert ax_hist2d.get_xlim() == ax_plot.get_xlim()
+    # sanity check: this is a small (date2num-like) scale, not raw datetime64
+    assert all(abs(lim) < 1e6 for lim in ax_hist2d.get_xlim())
+
+
+def test_hist2d_datetime_range():
+    # The `range` parameter should also be converted, so datetime bounds
+    # work the same way as passing already-converted (float) bounds.
+    x = np.arange(np.datetime64('2020-01-01'), np.datetime64('2020-01-11'))
+    y = np.arange(10.)
+    xlim = np.array([np.datetime64('2020-01-01'), np.datetime64('2020-01-11')])
+
+    h, xedges, yedges, pc = plt.figure().add_subplot().hist2d(
+        x, y, bins=5, range=[xlim, [0, 10]])
+    assert all(abs(e) < 1e6 for e in (xedges[0], xedges[-1]))
+
+
 class TestScatter:
     @image_comparison(['scatter'], style='mpl20', remove_text=True)
     def test_scatter_plot(self):