matplotlib
diff --git a/‎doc/api/next_api_changes/behavior/31223-AS.rst‎
Lines changed: 20 additions & 0 deletions b/‎doc/api/next_api_changes/behavior/31223-AS.rst‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎lib/matplotlib/pyplot.py‎
Lines changed: 7 additions & 0 deletions b/‎lib/matplotlib/pyplot.py‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎lib/matplotlib/tests/test_pyplot.py‎
Lines changed: 16 additions & 0 deletions b/‎lib/matplotlib/tests/test_pyplot.py‎
Lines changed: 16 additions & 0 deletions
@@ -0,0 +1,20 @@
+``pyplot.subplots`` raises *ValueError* if *num* refers to an existing figure
+--------------------------------------------------------------------------------
+
+Passing a *num* argument to `~.pyplot.subplots` that refers to an existing
+figure now raises a `ValueError`.  This prevents creating subplots on an
+existing figure without explicitly clearing it, which can lead to
+inconsistent state.
+
+To reuse an existing figure, clear it first using ``clear=True``:
+
+.. code-block:: python
+
+    fig, axs = plt.subplots(num=1, clear=True)
+
+Or close it first:
+
+.. code-block:: python
+
+    plt.close(1)
+    fig, axs = plt.subplots(num=1)
@@ -1856,6 +1856,13 @@ def subplots(
         fig, ax = plt.subplots(num=10, clear=True)
 
     """
+    num = fig_kw.get('num')
+    if num is not None and fignum_exists(num):
+        if not fig_kw.get('clear'):
+            raise ValueError(
+                f"Figure {num!r} already exists. Use plt.figure({num!r}) "
+                "to get it or plt.close({num!r}) to close it. "
+                "Alternatively, pass 'clear=True' to subplots().")
     fig = figure(**fig_kw)
     axs = fig.subplots(nrows=nrows, ncols=ncols, sharex=sharex, sharey=sharey,
                        squeeze=squeeze, subplot_kw=subplot_kw,
 
@@ -532,3 +532,19 @@ def assert_same_signature(func1, func2):
 
 def test_setloglevel_signature():
     assert_same_signature(plt.set_loglevel, mpl.set_loglevel)
+
+
+def test_subplots_reuse_existing_figure_error():
+    """Test interaction of plt.subplots(num=...) with existing figures."""
+    # Create a figure with a specific number first.
+    fig = plt.figure(1)
+
+    # Case 1: Reusing without clear=True should raise ValueError
+    with pytest.raises(ValueError, match="already exists"):
+        plt.subplots(num=1)
+
+    # Case 2: Reusing WITH clear=True should work fine (no error)
+    fig_new, axs = plt.subplots(num=1, clear=True)
+    assert fig_new is fig  # It should reuse the same figure object
+
+    plt.close(1)