matplotlib · timhoffm · Jan 15, 2026
diff --git a/doc/release/next_whats_new/add_axes.rst b/doc/release/next_whats_new/add_axes.rst
@@ -0,0 +1,7 @@
+``Figure.add_axes()`` without parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`.Figure.add_axes` can now be called without parameters to add a full-figure
+`~.axes.Axes`. This is equivalent to calling ``fig.add_subplot()`` without
+parameters. This also creates the same Axes as ``fig, ax = plt.subplots()``
+does.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -535,9 +535,20 @@ def add_axes(self, *args, **kwargs):
 
         Call signatures::
 
+            add_axes()
             add_axes(rect, projection=None, polar=False, **kwargs)
             add_axes(ax)
 
+        Without parameters a "standard" Axes is created that fills the figure.
+        ``fig = plt.figure(), ax = fig.add_axes()`` is equivalent to
+        ``fig, ax = plt.subplots()``.
+
+        If a *rect* tuple is passed, a new Axes is created at the given figure
+        coordinates.
+
+        Passing an existing `~.axes.Axes` instance *ax* adds it to the figure.
+        This is only for rare use cases. See the notes section below.
+
         Parameters
         ----------
         rect : tuple (left, bottom, width, height)
@@ -613,15 +624,17 @@ def add_axes(self, *args, **kwargs):
             fig.delaxes(ax)
             fig.add_axes(ax)
         """
-
-        if not len(args) and 'rect' not in kwargs:
-            raise TypeError("add_axes() missing 1 required positional argument: 'rect'")
-        elif 'rect' in kwargs:
+        if 'rect' in kwargs:
+            # handle add_axes(rect=[...]) as add_axes([...])
             if len(args):
                 raise TypeError("add_axes() got multiple values for argument 'rect'")
             args = (kwargs.pop('rect'), )
-        if len(args) != 1:
-            raise _api.nargs_error("add_axes", 1, len(args))
+
+        if len(args) > 1:
+            raise _api.nargs_error("add_axes", "0 or 1", len(args))
+
+        if not args:
+            return self.add_subplot()
 
         if isinstance(args[0], Axes):
             a, = args
@@ -648,10 +661,10 @@ def add_subplot(self, *args, **kwargs):
 
         Call signatures::
 
+           add_subplot()
            add_subplot(nrows, ncols, index, **kwargs)
            add_subplot(pos, **kwargs)
            add_subplot(ax)
-           add_subplot()
 
         Parameters
         ----------

diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -10,6 +10,7 @@
 import numpy as np
 import pytest
 from PIL import Image
+from numpy.testing import assert_array_equal
 
 import matplotlib as mpl
 from matplotlib import gridspec
@@ -534,11 +535,14 @@ def test_invalid_figure_size(width, height):
         fig.set_size_inches(width, height)
 
 
+def test_add_axes():
+    fig, ax = plt.subplots()
+    ax2 = plt.figure(2).add_axes()
+    assert_array_equal(ax2.get_position().get_points(), ax.get_position().get_points())
+
+
 def test_invalid_figure_add_axes():
     fig = plt.figure()
-    with pytest.raises(TypeError,
-                       match="missing 1 required positional argument: 'rect'"):
-        fig.add_axes()
 
     with pytest.raises(ValueError):
         fig.add_axes((.1, .1, .5, np.nan))
@@ -553,10 +557,10 @@ def test_invalid_figure_add_axes():
         fig.add_axes(ax)
 
     fig2.delaxes(ax)
-    with pytest.raises(TypeError, match=r"add_axes\(\) takes 1 positional arguments"):
+    with pytest.raises(TypeError, match=r"add_axes\(\) takes 0 or 1 positional"):
         fig2.add_axes(ax, "extra positional argument")
 
-    with pytest.raises(TypeError, match=r"add_axes\(\) takes 1 positional arguments"):
+    with pytest.raises(TypeError, match=r"add_axes\(\) takes 0 or 1 positional"):
         fig.add_axes((0, 0, 1, 1), "extra positional argument")