matplotlib · timhoffm · Apr 1, 2025
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -908,6 +908,10 @@
         window title is set to this value.  If num is a ``SubFigure``, its
         parent ``Figure`` is activated.
 
+        If *num* is a Figure instance that is already tracked in pyplot, it is
+        activated. If *num* is a Figure instance that is not tracked in pyplot,
+        it is added to the the tracked figures and activated.
+
     figsize : (float, float), default: :rc:`figure.figsize`
         Width, height in inches.
 
@@ -990,21 +994,32 @@
     in the matplotlibrc file.
     """
     allnums = get_fignums()
+    next_num = max(allnums) + 1 if allnums else 1
 
     if isinstance(num, FigureBase):
         # type narrowed to `Figure | SubFigure` by combination of input and isinstance
+        has_figure_property_parameters = (
+            any(param is not None for param in [figsize, dpi, facecolor, edgecolor])
+            or not frameon or kwargs
+        )
+
         root_fig = num.get_figure(root=True)
         if root_fig.canvas.manager is None:
-            raise ValueError("The passed figure is not managed by pyplot")
-        elif (any(param is not None for param in [figsize, dpi, facecolor, edgecolor])
-              or not frameon or kwargs) and root_fig.canvas.manager.num in allnums:
+            if has_figure_property_parameters:
+                raise ValueError(
+                    "You cannot pass figure properties when calling figure() with "
+                    "an existing Figure instance")
+            backend = _get_backend_mod()
+            manager_ = backend.new_figure_manager_given_figure(next_num, root_fig)
+            _pylab_helpers.Gcf._set_new_active_manager(manager_)
+            return manager_.canvas.figure
+        elif has_figure_property_parameters and root_fig.canvas.manager.num in allnums:
             _api.warn_external(
                 "Ignoring specified arguments in this call because figure "
                 f"with num: {root_fig.canvas.manager.num} already exists")
         _pylab_helpers.Gcf.set_active(root_fig.canvas.manager)
         return root_fig
 
-    next_num = max(allnums) + 1 if allnums else 1
     fig_label = ''
     if num is None:
         num = next_num

diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -147,8 +147,6 @@ def test_figure_label():
     assert plt.get_figlabels() == ['', 'today']
     plt.figure(fig_today)
     assert plt.gcf() == fig_today
-    with pytest.raises(ValueError):
-        plt.figure(Figure())
 
 
 def test_figure_label_replaced():

diff --git a/lib/matplotlib/tests/test_pyplot.py b/lib/matplotlib/tests/test_pyplot.py
@@ -470,6 +470,30 @@ def test_multiple_same_figure_calls():
     assert fig is fig3
 
 
+def test_register_existing_figure_with_pyplot():
+    from matplotlib.figure import Figure
+    # start with a standalone figure
+    fig = Figure()
+    assert fig.canvas.manager is None
+    with pytest.raises(AttributeError):
+        # Heads-up: This will change to returning None in the future
+        # See docstring for the Figure.number property
+        fig.number
+    # register the Figure with pyplot
+    plt.figure(fig)
+    assert fig.number == 1
+    # the figure can now be used in pyplot
+    plt.suptitle("my title")
+    assert fig.get_suptitle() == "my title"
+    # it also has a manager that is properly wired up in the pyplot state
+    assert plt._pylab_helpers.Gcf.get_fig_manager(fig.number) is fig.canvas.manager
+    # and we can regularly switch the pyplot state
+    fig2 = plt.figure()
+    assert fig2.number == 2
+    assert plt.figure(1) is fig
+    assert plt.gcf() is fig
+
+
 def test_close_all_warning():
     fig1 = plt.figure()