<spanid="mpl-shell"></span><h1>Interactive figures<aclass="headerlink" href="#interactive-figures" title="Permalink to this heading">#</a></h1>
<p>When working with data, interactivity can be invaluable. The pan/zoom and
mouse-location tools built into the Matplotlib GUI windows are often sufficient, but
you can also use the event system to build customized data exploration tools.</p>
<p>Matplotlib ships with <aclass="reference internal" href="backends.html#what-is-a-backend"><spanclass="std std-ref">backends</span></a> binding to
several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party
packages provide bindings to <aclass="reference external" href="https://github.com/kivy-garden/garden.matplotlib">kivy</a> and <aclass="reference external" href="https://matplotlib.org/ipympl">Jupyter Lab</a>. For the figures to be responsive to
mouse, keyboard, and paint events, the GUI event loop needs to be integrated
with an interactive prompt. We recommend using IPython (see <aclass="reference internal" href="#ipython-pylab"><spanclass="std std-ref">below</span></a>).</p>
<dt><aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.figure</span></code></a></dt><dd><p>Creates a new empty <aclass="reference internal" href="../../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Figure</span></code></a> or selects an existing figure</p>
</dd>
<dt><aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.subplots.html#matplotlib.pyplot.subplots" title="matplotlib.pyplot.subplots"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.subplots</span></code></a></dt><dd><p>Creates a new <aclass="reference internal" href="../../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Figure</span></code></a> and fills it with a grid of <aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Axes</span></code></a></p>
</dd>
</dl>
<p><aclass="reference internal" href="../../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot</span></code></a> has a notion of "The Current Figure" which can be accessed
through <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.gcf.html#matplotlib.pyplot.gcf" title="matplotlib.pyplot.gcf"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.gcf</span></code></a> and a notion of "The Current Axes" accessed
through <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.gca.html#matplotlib.pyplot.gca" title="matplotlib.pyplot.gca"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.gca</span></code></a>. Almost all of the functions in <aclass="reference internal" href="../../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot</span></code></a> pass
through the current <aclass="reference internal" href="../../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Figure</span></code></a> / <aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Axes</span></code></a> (or create one) as
appropriate.</p>
<p>Matplotlib keeps a reference to all of the open figures
created via <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.figure</span></code></a> or <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.subplots.html#matplotlib.pyplot.subplots" title="matplotlib.pyplot.subplots"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.subplots</span></code></a> so that the figures will not be garbage
collected. <aclass="reference internal" href="../../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Figure</span></code></a>s can be closed and deregistered from <aclass="reference internal" href="../../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot</span></code></a> individually via
<aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.close.html#matplotlib.pyplot.close" title="matplotlib.pyplot.close"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.close</span></code></a>; all open <aclass="reference internal" href="../../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Figure</span></code></a>s can be closed via <codeclass="docutils literal notranslate"><spanclass="pre">plt.close('all')</span></code>.</p>
<p>For more discussion of Matplotlib's event system and integrated event loops, please read:</p>
<blockquote>
<div><ulclass="simple">
<li><p><aclass="reference internal" href="interactive_guide.html#interactive-figures-and-eventloops"><spanclass="std std-ref">Interactive figures and asynchronous programming</span></a></p></li>
<li><p><aclass="reference internal" href="event_handling.html#event-handling-tutorial"><spanclass="std std-ref">Event handling and picking</span></a></p></li>
</ul>
</div></blockquote>
<sectionid="ipython-integration">
<spanid="ipython-pylab"></span><h2>IPython integration<aclass="headerlink" href="#ipython-integration" title="Permalink to this heading">#</a></h2>
<p>We recommend using IPython for an interactive shell. In addition to
all of its features (improved tab-completion, magics, multiline editing, etc),
it also ensures that the GUI toolkit event loop is properly integrated
with the command line (see <aclass="reference internal" href="interactive_guide.html#cp-integration"><spanclass="std std-ref">Command prompt integration</span></a>).</p>
<p>In this example, we create and modify a figure via an IPython prompt.
The figure displays in a QtAgg GUI window. To configure the integration
and enable <aclass="reference internal" href="#controlling-interactive"><spanclass="std std-ref">interactive mode</span></a> use the
<p>In recent versions of <codeclass="docutils literal notranslate"><spanclass="pre">Matplotlib</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">IPython</span></code>, it is
Using the <codeclass="docutils literal notranslate"><spanclass="pre">%</span></code> magic is guaranteed to work in all versions of Matplotlib and IPython.</p>
</section>
<sectionid="interactive-mode">
<spanid="controlling-interactive"></span><h2>Interactive mode<aclass="headerlink" href="#interactive-mode" title="Permalink to this heading">#</a></h2>
<td><p>Run the GUI event loop for <em>interval</em> seconds.</p></td>
</tr>
</tbody>
</table>
<p>Interactive mode controls:</p>
<ulclass="simple">
<li><p>whether created figures are automatically shown</p></li>
<li><p>whether changes to artists automatically trigger re-drawing existing figures</p></li>
<li><p>when <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.show.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.show()</span></code></a> returns if given no arguments: immediately, or after all of the figures have been closed</p></li>
</ul>
<p>If in interactive mode:</p>
<ulclass="simple">
<li><p>newly created figures will be displayed immediately</p></li>
<li><p>figures will automatically redraw when elements are changed</p></li>
<li><p><aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.show.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.show()</span></code></a> displays the figures and immediately returns</p></li>
</ul>
<p>If not in interactive mode:</p>
<ulclass="simple">
<li><p>newly created figures and changes to figures are not displayed until</p>
<li><p><aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.show.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.show()</span></code></a> runs the GUI event loop and does not return until all the plot windows are closed</p></li>
</ul>
<p>If you are in non-interactive mode (or created figures while in
non-interactive mode) you may need to explicitly call <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.show.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.show</span></code></a>
to display the windows on your screen. If you only want to run the
GUI event loop for a fixed amount of time, you can use <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.pause.html#matplotlib.pyplot.pause" title="matplotlib.pyplot.pause"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.pause</span></code></a>.
This will block the progress of your code as if you had called
<aclass="reference external" href="https://docs.python.org/3/library/time.html#time.sleep" title="(in Python v3.11)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">time.sleep</span></code></a>, ensure the current window is shown and re-drawn if needed,
and run the GUI event loop for the specified period of time.</p>
<p>The GUI event loop being integrated with your command prompt and
the figures being in interactive mode are independent of each other.
If you try to use <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.ion.html#matplotlib.pyplot.ion" title="matplotlib.pyplot.ion"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.ion</span></code></a> without arranging for the event-loop integration,
your figures will appear but will not be interactive while the prompt is waiting for input.
You will not be able to pan/zoom and the figure may not even render
(the window might appear black, transparent, or as a snapshot of the
desktop under it). Conversely, if you configure the event loop
integration, displayed figures will be responsive while waiting for input
at the prompt, regardless of pyplot's "interactive mode".</p>
<p>No matter what combination of interactive mode setting and event loop integration,
figures will be responsive if you use <codeclass="docutils literal notranslate"><spanclass="pre">pyplot.show(block=True)</span></code>, <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.pause.html#matplotlib.pyplot.pause" title="matplotlib.pyplot.pause"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.pause</span></code></a>, or run
the GUI main loop in some other way.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>Using <aclass="reference internal" href="../../api/figure_api.html#matplotlib.figure.Figure.show" title="matplotlib.figure.Figure.show"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Figure.show</span></code></a> it is possible to display a figure on
the screen without starting the event loop and without being in
interactive mode. This may work (depending on the GUI toolkit) but
will likely result in a non-responsive figure.</p>
</div>
</section>
<sectionid="default-ui">
<spanid="navigation-toolbar"></span><h2>Default UI<aclass="headerlink" href="#default-ui" title="Permalink to this heading">#</a></h2>
<p>The windows created by <aclass="reference internal" href="../../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">pyplot</span></code></a> have an interactive toolbar with navigation
buttons and a readout of the data values the cursor is pointing at. A number of
helpful keybindings are registered by default.</p>
<sectionid="navigation-keyboard-shortcuts">
<spanid="key-event-handling"></span><h3>Navigation keyboard shortcuts<aclass="headerlink" href="#navigation-keyboard-shortcuts" title="Permalink to this heading">#</a></h3>
<p>The following table holds all the default keys, which can be
overwritten by use of your <aclass="reference internal" href="../../tutorials/introductory/customizing.html"><spanclass="doc">matplotlibrc</span></a>.</p>