API: Raise ValueError in subplots if num refers to existing figure by Aaratrika-Shelly · Pull Request #31230 · matplotlib/matplotlib

Aaratrika-Shelly · 2026-03-03T10:21:40Z

PR summary

This PR updates pyplot.subplots to raise a ValueError if the num parameter refers to an existing figure, unless clear=True is also provided.

Why is this change necessary?
plt.subplots(num=1)) is ambiguous and can lead to inconsistent state or errors (like ValueError: The passed figure is not managed by pyplot`) in interactive environments, as described in the issue.
What problem does it solve?
It prevents users from unintentionally reusing figures in subplots calls, which is not the intended usage pattern.
What is the reasoning for this implementation?
Following the discussion with @timhoffm, the cleanest fix is to prohibit this pattern directly. A helpful error message guides the user to either retrieve the figure with plt.figure(num) or clear it with clear=True.

AI Disclosure

I used AI tools to help proofread and improve the grammar of this PR description. The code logic and implementation are my own work.

PR checklist

[n/a] "closes #0" is in the body of the PR description to link the related issue
[X ] new and changed code is tested
[ N/A] Plotting related features are demonstrated in an example
[ X] New Features and API Changes are noted with a directive and release note
[X ] Documentation complies with general and docstring guidelines

rcomer · 2026-03-03T15:29:49Z

lib/matplotlib/pyplot.py


    """
+    num = fig_kw.get('num')
+    if num is not None and fignum_exists(num):


The case from #31223 passed num=fig, where fig is a Figure instance. fignum_exists only works on integers, so I do not think this helps #31223.

In [1]: import matplotlib In [2]: matplotlib.__version__ Out[2]: '3.10.8' In [3]: import matplotlib.pyplot as plt In [4]: fig = plt.figure() In [5]: plt.fignum_exists(fig) Out[5]: False

Thank you for catching that, @rcomer. You're absolutely right—fignum_exists only handles the integer/string case, so my current logic wouldn't have caught the num=fig pattern from the original issue.
I implemented it this way based on the earlier suggestion, but I see now we need a more robust check. Is the preferred approach here to add an explicit isinstance(num, Figure) check to see if num.canvas.manager exists, or is there a more unified helper in the codebase I should use to check if a "number or object" is already managed by pyplot?
I'm happy to update the logic and add a test case for passing the figure object once the best approach is decided. Thanks!

I'd go for the narrow check: Only allow int or str that are not an existing fignum. We've historically been a bit vague what fignum can be but we should narrow that down.

rcomer

I think we need to put this on hold until we confirm whether passing the figure to subplots really was the cause of the error in #31223. My check suggests not, but perhaps I made a mistake https://github.com/matplotlib/matplotlib/issues/31223#issuecomment-3992077696.

timhoffm · 2026-03-03T16:49:08Z

I think this can be independent. plt.subplots() should never act on existing figures, because that's a recipe for logical chaos, even if it does not cause matplotlib/ipympl#622.

PR valid for other reasons than the linked issue

rcomer · 2026-03-03T17:28:20Z

Should we have the same restriction for pyplot.subplot_mosaic?

Aaratrika-Shelly · 2026-03-03T19:43:21Z

Should we have the same restriction for pyplot.subplot_mosaic?

@rcomer That's an excellent suggestion. It makes sense to keep the behavior consistent across both utility functions.
I will go ahead and apply the same logic to subplot_mosaic, and I'll update the subplots check to explicitly block Figure instances as @timhoffm suggested. I'll push an updated commit once I've added tests for both scenarios. Thanks!

Aaratrika-Shelly · 2026-03-03T20:33:10Z

It looks like the new tests in test_pyplot.py are passing, but there are two failures in test_colorbar.py. Based on the traceback, these seem to be AssertionErrors unrelated to the ValueError logic I added to subplots. Please let me know if you'd like me to investigate further or if these are known flaky tests in the CI.

rcomer · 2026-03-03T21:52:22Z

I have not seen those colorbar failures before, but I do not see how they could have been caused by this PR. Since they are in the minimum version tests and involve logarithms and ticks, I suspect they have the same cause as the ones addressed at #30950.

The changenote needs updating to also mention subplot_mosaic.

tacaswell · 2026-03-04T20:39:17Z

I had some question if we want to go straight to error or start with a warning, but Tim's point in the issue about now wanting to accidentally register a figure with pyplot is a good one so we should go straight to error even if we risk breaking some users. I am sure there exists at least one user who is doing:

plt.subplots(3, 3, num=1, gridspec_kw={'left': 0, 'right':.5})
plt.subplots(num=1, gridspec_kw={'left': .5, 'right':1})

to layout a figure.

Aaratrika-Shelly · 2026-03-05T20:28:35Z

I had some question if we want to go straight to error or start with a warning, but Tim's point in the issue about now wanting to accidentally register a figure with pyplot is a good one so we should go straight to error even if we risk breaking some users. I am sure there exists at least one user who is doing:
plt.subplots(3, 3, num=1, gridspec_kw={'left': 0, 'right':.5})
plt.subplots(num=1, gridspec_kw={'left': .5, 'right':1})
to layout a figure.

"That's a great example, @tacaswell. I've added a specific test case (test_subplots_error_on_double_call) to ensure that this pattern is correctly caught and raises the intended ValueError. All tests are passing!"

rcomer · 2026-03-06T09:16:50Z

@Aaratrika-Shelly many of your responses here read like they are AI generated. Please read our policy on that.
https://matplotlib.org/devdocs/devel/contribute.html#generative-ai

Aaratrika-Shelly · 2026-03-06T09:32:08Z

@Aaratrika-Shelly many of your responses here read like they are AI generated. Please read our policy on that.
https://matplotlib.org/devdocs/devel/contribute.html#generative-ai

I am so sorry. Since I am pretty new to contributing in open source, I was using AI to help proofread my messages (as mentioned in the AI disclosure) to make sure I was being professional. I will not do that from now on.
The code has been written and understood by me.

timhoffm · 2026-03-06T10:21:10Z

lib/matplotlib/pyplot.py

+    num = fig_kw.get('num')
+    if num is not None:
+
+        if isinstance(num, Figure):


Please check for FigureBase.

timhoffm · 2026-03-06T10:25:51Z

lib/matplotlib/pyplot.py

+    if num is not None:
+
+        if isinstance(num, Figure):
+            raise ValueError(
+                f"num {num!r} cannot be a Figure instance. plt.subplots() "
+                "is for creating new figures. To add subplots to an existing "
+                "figure, use fig.subplots() instead.")
+
+        if fignum_exists(num) and 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().")


Please factor this out in a helper raise_if_figure_exists(num, func_name)

so that we can do raise_if_figure_exists(num, "subplots()") here.

The main reason is so that the validation details do not clutter the main task of the function. A secondary effect is to remove the redundancy / keep the messages in sync on both functions.

QuLogic · 2026-03-07T06:41:13Z

I've edited this to remove the closing magic tag as this PR does not fix the original issue directly, and the issue's been moved to the ipympl repo.

rcomer · 2026-03-09T14:45:41Z

I think I am still confused about the rationale for doing this, and the explanation in the changenote is not really clearing that confusion. What do we mean by "inconsistent state"? What do we mean by "desynchronized internal state"?

We are happy with the idea that you can use plt.figure to either switch to an existing figure managed by pyplot or register one that previously wasn't with pyplot. All plt.subplots does is follow that with a call to fig.subplots(). What is the added danger there?

On the point about not wanting to accidentally register a figure, I agree that this would be a weird pattern

fig = Figure()
plt.subplots(..., num=fig)

but it is explicit so I think hard to do accidentally.

timhoffm · 2026-03-09T15:44:18Z

The point is that plt.subplots documents itself as

Create a figure and a set of subplots.

It is not intended to be used with existing figures, and I consider this a feature because it is a simple "create the basic structure" function. Supporting num needed so that you can give the figure a name. That is legitimate. Since this is internally realized by plt.figure(num) we accidentally accept existing figures (pyplot nums or now even standalone Figures). We only want "create a figure with this num" but since plt.figure(num) has a richer semantics that's inherited.

rcomer · 2026-03-11T10:13:35Z

doc/api/next_api_changes/behavior/31223-AS.rst

+This prevents creating subplots or mosaics on an existing figure without
+explicitly clearing it, which can lead to inconsistent state. Previously,
+passing a ``Figure`` instance could lead to a desynchronized internal state.


I do not understand this paragraph. Please can you update it to either make it clearer what problematic state the figure could get into, or to reflect the explanation given at #31230 (comment), which I think is clear.

rcomer · 2026-03-11T10:17:39Z

lib/matplotlib/tests/test_pyplot.py

+def test_subplots_error_on_double_call():
+    """
+    Test that calling subplots twice on the same figure raises an error.
+    This ensures that multiple calls to subplots on the same figure number
+    without clear=True are correctly prohibited.
+    """
+
+    plt.subplots(3, 3, num=1, gridspec_kw={'left': 0, 'right': 0.5})
+
+    with pytest.raises(ValueError, match="already exists"):
+        plt.subplots(num=1, gridspec_kw={'left': 0.5, 'right': 1})
+
+    plt.close(1)


Do we really need this test? I'm struggling to think of a scenario that might break this one without also breaking test_subplots_reuse_existing_figure_error.

My reading of @tacaswell's comment was not that we explicitly want to prohibit this sort of case, but rather this is a fairly reasonable case that will be prohibited as a side-effect of this change.

I have removed the test case. I got confused about what was needed.

rcomer · 2026-03-11T20:52:07Z

Thank you for your work on this @Aaratrika-Shelly. I think this is ready to go and anyone can merge when CI has passed.

timhoffm · 2026-03-11T21:28:48Z

Thanks @Aaratrika-Shelly !

…y/fix/subplots-reuse-error

github-actions bot added the topic: pyplot API label Mar 3, 2026

Aaratrika-Shelly force-pushed the fix/subplots-reuse-error branch from d9f11c2 to 06ab8ab Compare March 3, 2026 10:48

timhoffm approved these changes Mar 3, 2026

View reviewed changes

rcomer reviewed Mar 3, 2026

View reviewed changes

rcomer previously requested changes Mar 3, 2026

View reviewed changes

timhoffm mentioned this pull request Mar 3, 2026

[Bug]: Intermittent ValueError: The passed figure is not managed by pyplot with ipympl (%matplotlib widget) matplotlib/ipympl#622

Open

Aaratrika-Shelly force-pushed the fix/subplots-reuse-error branch from 06ab8ab to 2aa3085 Compare March 3, 2026 20:08

Aaratrika-Shelly requested review from rcomer and timhoffm March 3, 2026 20:09

Aaratrika-Shelly force-pushed the fix/subplots-reuse-error branch 2 times, most recently from e922ee3 to c9ba0e6 Compare March 4, 2026 19:03

Aaratrika-Shelly force-pushed the fix/subplots-reuse-error branch from c9ba0e6 to f8f0a92 Compare March 5, 2026 20:28

Aaratrika-Shelly force-pushed the fix/subplots-reuse-error branch from f8f0a92 to 89a60fe Compare March 5, 2026 20:32

rcomer removed their request for review March 6, 2026 08:46

timhoffm reviewed Mar 6, 2026

View reviewed changes

Aaratrika-Shelly force-pushed the fix/subplots-reuse-error branch from 89a60fe to ab5e1c7 Compare March 7, 2026 19:03

timhoffm approved these changes Mar 8, 2026

View reviewed changes

rcomer reviewed Mar 11, 2026

View reviewed changes

API: Raise ValueError in subplots if num refers to existing figure

904d093

Aaratrika-Shelly force-pushed the fix/subplots-reuse-error branch from ab5e1c7 to 904d093 Compare March 11, 2026 20:26

rcomer added this to the v3.11.0 milestone Mar 11, 2026

rcomer approved these changes Mar 11, 2026

View reviewed changes

timhoffm merged commit ffb2e6e into matplotlib:main Mar 11, 2026
34 of 37 checks passed

andreas16700 added a commit to andreas16700/matplotlib that referenced this pull request Mar 16, 2026

Run ffb2e6e: Merge pull request matplotlib#31230 from Aaratrika-Shell…

afea969

…y/fix/subplots-reuse-error

andreas16700 added a commit to andreas16700/matplotlib that referenced this pull request Mar 16, 2026

Run ffb2e6e: Merge pull request matplotlib#31230 from Aaratrika-Shell…

6ee3a21

…y/fix/subplots-reuse-error

Uh oh!

Conversation

Aaratrika-Shelly commented Mar 3, 2026 • edited by QuLogic Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR summary

AI Disclosure

PR checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rcomer left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm commented Mar 3, 2026

Uh oh!

rcomer commented Mar 3, 2026

Uh oh!

Aaratrika-Shelly commented Mar 3, 2026

Uh oh!

Aaratrika-Shelly commented Mar 3, 2026

Uh oh!

rcomer commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tacaswell commented Mar 4, 2026

Uh oh!

Aaratrika-Shelly commented Mar 5, 2026

Uh oh!

rcomer commented Mar 6, 2026

Uh oh!

Aaratrika-Shelly commented Mar 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QuLogic commented Mar 7, 2026

Uh oh!

rcomer commented Mar 9, 2026

Uh oh!

timhoffm commented Mar 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rcomer commented Mar 11, 2026

Uh oh!

Uh oh!

timhoffm commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Aaratrika-Shelly commented Mar 3, 2026 •

edited by QuLogic

Loading

rcomer commented Mar 3, 2026 •

edited

Loading