From c8361f0a33c8e88abf8f3862dce8388bd1a00eac Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Wed, 2 Jul 2025 07:36:04 +0200
Subject: [PATCH] DOC: Recommend to use bare Figure instances for saving to
 file

---
 doc/users/faq.rst | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/doc/users/faq.rst b/doc/users/faq.rst
index b08bd75cee4e..c6bbc5ca8d87 100644
--- a/doc/users/faq.rst
+++ b/doc/users/faq.rst
@@ -281,8 +281,23 @@ locators as desired because the two axes are independent.
 Generate images without having a window appear
 ----------------------------------------------
 
-Simply do not call `~matplotlib.pyplot.show`, and directly save the figure to
-the desired format::
+The recommended approach since matplotlib 3.1 is to explicitly create a Figure
+instance::
+
+    from matplotlib.figure import Figure
+    fig = Figure()
+    ax = fig.subplots()
+    ax.plot([1, 2, 3])
+    fig.savefig('myfig.png')
+
+This prevents any interaction with GUI frameworks and the window manager.
+
+It's alternatively still possible to use the pyplot interface. Instead of
+calling `matplotlib.pyplot.show`, call `matplotlib.pyplot.savefig`.
+
+Additionally, you must ensure to close the figure after saving it. Not
+closing the figure is a memory leak, because pyplot keeps references
+to all not-yet-shown figures::
 
     import matplotlib.pyplot as plt
     plt.plot([1, 2, 3])