Improve docs regarding plt.close().

anntzer · anntzer · commit d35988ede593 · 2025-03-31T15:20:02.000+02:00
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
@@ -1171,8 +1171,8 @@ def disconnect(cid: int) -> None:
 
 
 def close(fig: None | int | str | Figure | Literal["all"] = None) -> None:
-    """
-    Close a figure window.
+    r"""
+    Close a figure window, and unregister it from pyplot.
 
     Parameters
     ----------
@@ -1185,6 +1185,11 @@ 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()` until they
+    are `close()`\ d.  Closing figures is thus necessary to prevent running out
+    of memory (see also :rc:`figure.max_open_warning`).
     """
     if fig is None:
         manager = _pylab_helpers.Gcf.get_active()
