Merge pull request #29848 from meeseeksmachine/auto-backport-of-pr-29839-on-v3.10.x

timhoffm · web-flow · commit ba588a52305a · 2025-04-01T15:48:31.000+02:00
Backport PR #29839 on branch v3.10.x (Improve docs regarding plt.close().)
diff --git a/doc/users/faq.rst b/doc/users/faq.rst
@@ -287,6 +287,7 @@ the desired format::
     import matplotlib.pyplot as plt
     plt.plot([1, 2, 3])
     plt.savefig('myfig.png')
+    plt.close()
 
 .. seealso::
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1170,7 +1170,7 @@ def disconnect(cid: int) -> None:
 
 def close(fig: None | int | str | Figure | Literal["all"] = None) -> None:
     """
-    Close a figure window.
+    Close a figure window, and unregister it from pyplot.
 
     Parameters
     ----------
@@ -1183,6 +1183,14 @@ def close(fig: None | int | str | Figure | Literal["all"] = None) -> None:
         - ``str``: a figure name
         - 'all': all figures
 
+    Notes
+    -----
+    pyplot maintains a reference to figures created with `figure()`. When
+    work on the figure is completed, it should be closed, i.e. deregistered
+    from pyplot, to free its memory (see also :rc:figure.max_open_warning).
+    Closing a figure window created by `show()` automatically deregisters the
+    figure. For all other use cases, most prominently `savefig()` without
+    `show()`, the figure must be deregistered explicitly using `close()`.
     """
     if fig is None:
         manager = _pylab_helpers.Gcf.get_active()
