You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<li><aclass="reference internal" href="#types-of-inputs-to-plotting-functions" id="id12">Types of inputs to plotting functions</a></li>
<li><aclass="reference internal" href="#matplotlib-pyplot-and-pylab-how-are-they-related" id="id13">Matplotlib, pyplot and pylab: how are they related?</a></li>
<spanid="id1"></span><h2>General Concepts<aclass="headerlink" href="#general-concepts" title="Permalink to this headline">¶</a></h2>
<p><codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib</span></code> has an extensive codebase that can be daunting to many
new users. However, most of matplotlib can be understood with a fairly
simple conceptual framework and knowledge of a few important points.</p>
<p>Plotting requires action on a range of levels, from the most general
(e.g., ‘contour this 2-D array’) to the most specific (e.g., ‘color
this screen pixel red’). The purpose of a plotting package is to assist
you in visualizing your data as easily as possible, with all the necessary
control – that is, by using relatively high-level commands most of
the time, and still have the ability to use the low-level commands when
needed.</p>
<p>Therefore, everything in matplotlib is organized in a hierarchy. At the top
of the hierarchy is the matplotlib “state-machine environment” which is
provided by the <aclass="reference internal" href="../api/pyplot_api.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib.pyplot</span></code></a> module. At this level, simple
functions are used to add plot elements (lines, images, text, etc.) to
the current axes in the current figure.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Pyplot’s state-machine environment behaves similarly to MATLAB and
should be most familiar to users with MATLAB experience.</p>
</div>
<p>The next level down in the hierarchy is the first level of the object-oriented
interface, in which pyplot is used only for a few functions such as figure
creation, and the user explicitly creates and keeps track of the figure
and axes objects. At this level, the user uses pyplot to create figures,
and through those figures, one or more axes objects can be created. These
axes objects are then used for most plotting actions.</p>
<p>For even more control – which is essential for things like embedding
matplotlib plots in GUI applications – the pyplot level may be dropped
completely, leaving a purely object-oriented approach.</p>
</div>
<divclass="section" id="parts-of-a-figure">
<spanid="figure-parts"></span><h2>Parts of a Figure<aclass="headerlink" href="#parts-of-a-figure" title="Permalink to this headline">¶</a></h2>
<h3><aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-class docutils literal"><spanclass="pre">Figure</span></code></a><aclass="headerlink" href="#figure" title="Permalink to this headline">¶</a></h3>
<p>The <strong>whole</strong> figure (marked as the outer red box). The figure keeps
track of all the child <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a>, a smattering of
‘special’ artists (titles, figure legends, etc), and the <strong>canvas</strong>.
(Don’t worry too much about the canvas, it is crucial as it is the
object that actually does the drawing to get you your plot, but as the
user it is more-or-less invisible to you). A figure can have any
number of <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a>, but to be useful should have
at least one.</p>
<p>The easiest way to create a new figure is with pyplot:</p>
<divclass="highlight-python"><divclass="highlight"><pre><spanclass="n">fig</span><spanclass="o">=</span><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">figure</span><spanclass="p">()</span><spanclass="c1"># an empty figure with no axes</span>
<spanclass="n">fig</span><spanclass="p">,</span><spanclass="n">ax_lst</span><spanclass="o">=</span><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">subplots</span><spanclass="p">(</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">)</span><spanclass="c1"># a figure with a 2x2 grid of Axes</span>
</pre></div>
</div>
</div>
<divclass="section" id="axes">
<h3><aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a><aclass="headerlink" href="#axes" title="Permalink to this headline">¶</a></h3>
<p>This is what you think of as ‘a plot’, it is the region of the image
with the data space (marked as the inner blue box). A given figure
can contain many Axes, but a given <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a>
object can only be in one <aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-class docutils literal"><spanclass="pre">Figure</span></code></a>. The
Axes contains two (or three in the case of 3D)
<aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis" title="matplotlib.axis.Axis"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axis</span></code></a> objects (be aware of the difference
between <strong>Axes</strong> and <strong>Axis</strong>) which take care of the data limits (the
data limits can also be controlled via set via the
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_xlim" title="matplotlib.axes.Axes.set_xlim"><codeclass="xref py py-meth docutils literal"><spanclass="pre">set_xlim()</span></code></a> and
<codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code> has a title (set via
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_title" title="matplotlib.axes.Axes.set_title"><codeclass="xref py py-meth docutils literal"><spanclass="pre">set_title()</span></code></a>), an x-label (set via
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_xlabel" title="matplotlib.axes.Axes.set_xlabel"><codeclass="xref py py-meth docutils literal"><spanclass="pre">set_xlabel()</span></code></a>), and a y-label set via
<p>The <codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code> class and it’s member functions are the primary entry
point to working with the OO interface.</p>
</div>
<divclass="section" id="axis">
<h3><aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis" title="matplotlib.axis.Axis"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axis</span></code></a><aclass="headerlink" href="#axis" title="Permalink to this headline">¶</a></h3>
<p>These are the number-line-like objects (circled in green). They take
care of setting the graph limits and generating the ticks (the marks
on the axis) and ticklabels (strings labeling the ticks). The
location of the ticks is determined by a
<aclass="reference internal" href="../api/ticker_api.html#matplotlib.ticker.Locator" title="matplotlib.ticker.Locator"><codeclass="xref py py-class docutils literal"><spanclass="pre">Locator</span></code></a> object and the ticklabel strings
are formatted by a <aclass="reference internal" href="../api/ticker_api.html#matplotlib.ticker.Formatter" title="matplotlib.ticker.Formatter"><codeclass="xref py py-class docutils literal"><spanclass="pre">Formatter</span></code></a>. The
combination of the correct <codeclass="xref py py-class docutils literal"><spanclass="pre">Locator</span></code> and <codeclass="xref py py-class docutils literal"><spanclass="pre">Formatter</span></code> gives
very fine control over the tick locations and labels.</p>
</div>
<divclass="section" id="artist">
<h3><aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-class docutils literal"><spanclass="pre">Artist</span></code></a><aclass="headerlink" href="#artist" title="Permalink to this headline">¶</a></h3>
<p>Basically everything you can see on the figure is an artist (even the
<codeclass="xref py py-class docutils literal"><spanclass="pre">Figure</span></code>, <codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code>, and <codeclass="xref py py-class docutils literal"><spanclass="pre">Axis</span></code> objects). This
<spanid="input-types"></span><h2>Types of inputs to plotting functions<aclass="headerlink" href="#types-of-inputs-to-plotting-functions" title="Permalink to this headline">¶</a></h2>
<p>All of plotting functions expect <codeclass="xref py py-obj docutils literal"><spanclass="pre">np.array</span></code> or <codeclass="xref py py-obj docutils literal"><spanclass="pre">np.ma.masked_array</span></code> as
input. Classes that are ‘array-like’ such as <codeclass="xref py py-obj docutils literal"><spanclass="pre">pandas</span></code> data objects
and <codeclass="xref py py-obj docutils literal"><spanclass="pre">np.matrix</span></code> may or may not work as intended. It is best to
convert these to <codeclass="xref py py-obj docutils literal"><spanclass="pre">np.array</span></code> objects prior to plotting.</p>
<p>For example, to covert a <codeclass="xref py py-obj docutils literal"><spanclass="pre">pandas.DataFrame</span></code></p>
<spanid="pylab"></span><h2>Matplotlib, pyplot and pylab: how are they related?<aclass="headerlink" href="#matplotlib-pyplot-and-pylab-how-are-they-related" title="Permalink to this headline">¶</a></h2>
<p>Matplotlib is the whole package; <aclass="reference internal" href="../api/pyplot_api.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib.pyplot</span></code></a>
is a module in matplotlib; and <codeclass="xref py py-mod docutils literal"><spanclass="pre">pylab</span></code> is a module
that gets installed alongside <codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib</span></code>.</p>
<p>Pyplot provides the state-machine interface to the underlying
object-oriented plotting library. The state-machine implicitly and
automatically creates figures and axes to achieve the desired
<p>Again, for these simple examples this style seems like overkill, however
once the graphs get slightly more complex it pays off.</p>
</div>
<divclass="section" id="what-is-a-backend">
<spanid="id3"></span><h2>What is a backend?<aclass="headerlink" href="#what-is-a-backend" title="Permalink to this headline">¶</a></h2>
<p>A lot of documentation on the website and in the mailing lists refers
to the “backend” and many new users are confused by this term.
matplotlib targets many different use cases and output formats. Some
people use matplotlib interactively from the python shell and have
plotting windows pop up when they type commands. Some people embed
matplotlib into graphical user interfaces like wxpython or pygtk to
build rich applications. Others use matplotlib in batch scripts to
generate postscript images from some numerical simulations, and still
others in web application servers to dynamically serve up graphs.</p>
<p>To support all of these use cases, matplotlib can target different
outputs, and each of these capabilities is called a backend; the
“frontend” is the user facing code, i.e., the plotting code, whereas the
“backend” does all the hard work behind-the-scenes to make the figure.
There are two types of backends: user interface backends (for use in
pygtk, wxpython, tkinter, qt4, or macosx; also referred to as
“interactive backends”) and hardcopy backends to make image files
(PNG, SVG, PDF, PS; also referred to as “non-interactive backends”).</p>
<p>There are a four ways to configure your backend. If they conflict each other,
the method mentioned last in the following list will be used, e.g. calling
<aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.use" title="matplotlib.use"><codeclass="xref py py-func docutils literal"><spanclass="pre">use()</span></code></a> will override the setting in your <codeclass="docutils literal"><spanclass="pre">matplotlibrc</span></code>.</p>
<olclass="arabic">
<li><pclass="first">The <codeclass="docutils literal"><spanclass="pre">backend</span></code> parameter in your <codeclass="docutils literal"><spanclass="pre">matplotlibrc</span></code> file (see
<p>Setting this environment variable will override the <codeclass="docutils literal"><spanclass="pre">backend</span></code> parameter
in <em>any</em><codeclass="docutils literal"><spanclass="pre">matplotlibrc</span></code>, even if there is a <codeclass="docutils literal"><spanclass="pre">matplotlibrc</span></code> in your
current working directory. Therefore setting <spanclass="target" id="index-1"></span><aclass="reference internal" href="environment_variables_faq.html#envvar-MPLBACKEND"><codeclass="xref std std-envvar docutils literal"><spanclass="pre">MPLBACKEND</span></code></a>
globally, e.g. in your <codeclass="docutils literal"><spanclass="pre">.bashrc</span></code> or <codeclass="docutils literal"><spanclass="pre">.profile</span></code>, is discouraged as it
might lead to counter-intuitive behavior.</p>
</li>
<li><pclass="first">To set the backend for a single script, you can alternatively use the <codeclass="xref py py-obj docutils literal"><spanclass="pre">-d</span></code>
<p>This method is <strong>deprecated</strong> as the <codeclass="xref py py-obj docutils literal"><spanclass="pre">-d</span></code> argument might conflict with
scripts which parse command line arguments (see issue
<aclass="reference external" href="https://github.com/matplotlib/matplotlib/issues/1986">#1986</a>). You
should use <spanclass="target" id="index-2"></span><aclass="reference internal" href="environment_variables_faq.html#envvar-MPLBACKEND"><codeclass="xref std std-envvar docutils literal"><spanclass="pre">MPLBACKEND</span></code></a> instead.</p>
</li>
<li><pclass="first">If your script depends on a specific backend you can use the
<spanclass="n">matplotlib</span><spanclass="o">.</span><spanclass="n">use</span><spanclass="p">(</span><spanclass="s1">'PS'</span><spanclass="p">)</span><spanclass="c1"># generate postscript output by default</span>
</pre></div>
</div>
<p>If you use the <aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.use" title="matplotlib.use"><codeclass="xref py py-func docutils literal"><spanclass="pre">use()</span></code></a> function, this must be done before
pyplot has been imported will have no effect. Using
<aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.use" title="matplotlib.use"><codeclass="xref py py-func docutils literal"><spanclass="pre">use()</span></code></a> will require changes in your code if users want to
use a different backend. Therefore, you should avoid explicitly calling
<pclass="last">Backend name specifications are not case-sensitive; e.g., ‘GTKAgg’
and ‘gtkagg’ are equivalent.</p>
</div>
<p>With a typical installation of matplotlib, such as from a
binary installer or a linux distribution package, a good default
backend will already be set, allowing both interactive work and
plotting from scripts, with output to the screen and/or to
a file, so at least initially you will not need to use any of the
methods given above.</p>
<p>If, however, you want to write graphical user interfaces, or a web
application server (<aclass="reference internal" href="howto_faq.html#howto-webapp"><span>Matplotlib in a web application server</span></a>), or need a better
understanding of what is going on, read on. To make things a little
more customizable for graphical user interfaces, matplotlib separates
the concept of the renderer (the thing that actually does the drawing)
from the canvas (the place where the drawing goes). The canonical
renderer for user interfaces is <codeclass="docutils literal"><spanclass="pre">Agg</span></code> which uses the <aclass="reference external" href="http://antigrain.com/">Anti-Grain
Geometry</a> C++ library to make a raster (pixel) image of the figure.
All of the user interfaces except <codeclass="docutils literal"><spanclass="pre">macosx</span></code> can be used with
agg rendering, e.g.,
<codeclass="docutils literal"><spanclass="pre">WXAgg</span></code>, <codeclass="docutils literal"><spanclass="pre">GTKAgg</span></code>, <codeclass="docutils literal"><spanclass="pre">QT4Agg</span></code>, <codeclass="docutils literal"><spanclass="pre">TkAgg</span></code>. In
addition, some of the user interfaces support other rendering engines.
For example, with GTK, you can also select GDK rendering (backend
<codeclass="docutils literal"><spanclass="pre">GTK</span></code>) or Cairo rendering (backend <codeclass="docutils literal"><spanclass="pre">GTKCairo</span></code>).</p>
<p>For the rendering engines, one can also distinguish between <aclass="reference external" href="http://en.wikipedia.org/wiki/Vector_graphics">vector</a> or <aclass="reference external" href="http://en.wikipedia.org/wiki/Raster_graphics">raster</a> renderers. Vector
graphics languages issue drawing commands like “draw a line from this
point to this point” and hence are scale free, and raster backends
generate a pixel representation of the line whose accuracy depends on a
DPI setting.</p>
<p>Here is a summary of the matplotlib renderers (there is an eponymous
backed for each; these are <em>non-interactive backends</em>, capable of
the <aclass="reference external" href="http://en.wikipedia.org/wiki/GDK">Gimp Drawing Kit</a></td>
</tr>
</tbody>
</table>
<p>And here are the user interfaces and renderer combinations supported;
these are <em>interactive backends</em>, capable of displaying to the screen
and of using appropriate renderers from the table above to write to
a file:</p>
<tableborder="1" class="docutils">
<colgroup>
<colwidth="15%" />
<colwidth="85%" />
</colgroup>
<theadvalign="bottom">
<trclass="row-odd"><thclass="head">Backend</th>
<thclass="head">Description</th>
</tr>
</thead>
<tbodyvalign="top">
<trclass="row-even"><td>GTKAgg</td>
<td>Agg rendering to a <aclass="reference internal" href="../glossary/index.html#term-gtk"><spanclass="xref std std-term">GTK</span></a> 2.x canvas (requires <aclass="reference external" href="http://www.pygtk.org">PyGTK</a> and
<aclass="reference external" href="http://www.cairographics.org/pycairo/">pycairo</a> or <aclass="reference external" href="https://pythonhosted.org/cairocffi/">cairocffi</a>; Python2 only)</td>
</tr>
<trclass="row-odd"><td>GTK3Agg</td>
<td>Agg rendering to a <aclass="reference internal" href="../glossary/index.html#term-gtk"><spanclass="xref std std-term">GTK</span></a> 3.x canvas (requires <aclass="reference external" href="https://live.gnome.org/PyGObject">PyGObject</a>
and <aclass="reference external" href="http://www.cairographics.org/pycairo/">pycairo</a> or <aclass="reference external" href="https://pythonhosted.org/cairocffi/">cairocffi</a>)</td>
</tr>
<trclass="row-even"><td>GTK</td>
<td>GDK rendering to a <aclass="reference internal" href="../glossary/index.html#term-gtk"><spanclass="xref std std-term">GTK</span></a> 2.x canvas (not recommended)
(requires <aclass="reference external" href="http://www.pygtk.org">PyGTK</a> and <aclass="reference external" href="http://www.cairographics.org/pycairo/">pycairo</a> or <aclass="reference external" href="https://pythonhosted.org/cairocffi/">cairocffi</a>; Python2 only)</td>
</tr>
<trclass="row-odd"><td>GTKCairo</td>
<td>Cairo rendering to a <aclass="reference internal" href="../glossary/index.html#term-gtk"><spanclass="xref std std-term">GTK</span></a> 2.x canvas (requires <aclass="reference external" href="http://www.pygtk.org">PyGTK</a>
and <aclass="reference external" href="http://www.cairographics.org/pycairo/">pycairo</a> or <aclass="reference external" href="https://pythonhosted.org/cairocffi/">cairocffi</a>; Python2 only)</td>
</tr>
<trclass="row-even"><td>GTK3Cairo</td>
<td>Cairo rendering to a <aclass="reference internal" href="../glossary/index.html#term-gtk"><spanclass="xref std std-term">GTK</span></a> 3.x canvas (requires <aclass="reference external" href="https://live.gnome.org/PyGObject">PyGObject</a>
and <aclass="reference external" href="http://www.cairographics.org/pycairo/">pycairo</a> or <aclass="reference external" href="https://pythonhosted.org/cairocffi/">cairocffi</a>)</td>
</tr>
<trclass="row-odd"><td>WXAgg</td>
<td>Agg rendering to to a <aclass="reference internal" href="../glossary/index.html#term-wxwidgets"><spanclass="xref std std-term">wxWidgets</span></a> canvas
<td>Agg rendering to a <aclass="reference internal" href="../glossary/index.html#term-tk"><spanclass="xref std std-term">Tk</span></a> canvas (requires <aclass="reference external" href="http://wiki.python.org/moin/TkInter">TkInter</a>)</td>
</tr>
<trclass="row-even"><td>Qt4Agg</td>
<td>Agg rendering to a <aclass="reference internal" href="../glossary/index.html#term-qt4"><spanclass="xref std std-term">Qt4</span></a> canvas (requires <aclass="reference external" href="http://www.riverbankcomputing.co.uk/software/pyqt/intro">PyQt4</a> or <codeclass="docutils literal"><spanclass="pre">pyside</span></code>)</td>
</tr>
<trclass="row-odd"><td>Qt5Agg</td>
<td>Agg rendering in a <aclass="reference internal" href="../glossary/index.html#term-qt5"><spanclass="xref std std-term">Qt5</span></a> canvas (requires <aclass="reference external" href="http://www.riverbankcomputing.co.uk/software/pyqt/intro">PyQt5</a>)</td>
</tr>
<trclass="row-even"><td>macosx</td>
<td>Cocoa rendering in OSX windows
(presently lacks blocking show() behavior when matplotlib
is in non-interactive mode)</td>
</tr>
</tbody>
</table>
</div>
<divclass="section" id="wx-backends">
<h2>WX backends<aclass="headerlink" href="#wx-backends" title="Permalink to this headline">¶</a></h2>
<p>At present the release version of <codeclass="xref py py-obj docutils literal"><spanclass="pre">wxPython</span></code> (also known as wxPython classic)
does not support python3. A work in progress redesigned version known as
<aclass="reference external" href="http://wxpython.org/Phoenix/docs/html/main.html">wxPython-Phoenix</a> does support python3.
Matplotlib should work with both versions.</p>
</div>
<divclass="section" id="gtk-and-cairo">
<h2>GTK and Cairo<aclass="headerlink" href="#gtk-and-cairo" title="Permalink to this headline">¶</a></h2>
<p>Both <codeclass="xref py py-obj docutils literal"><spanclass="pre">GTK2</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">GTK3</span></code> have implicit dependencies on PyCairo regardless of the
specific Matplotlib backend used. Unfortunatly the latest release of PyCairo
for Python3 does not implement the Python wrappers needed for the <codeclass="xref py py-obj docutils literal"><spanclass="pre">GTK3Agg</span></code>
backend. <codeclass="xref py py-obj docutils literal"><spanclass="pre">Cairocffi</span></code> can be used as a replacement which implements the correct
<h2>How do I select PyQt4 or PySide?<aclass="headerlink" href="#how-do-i-select-pyqt4-or-pyside" title="Permalink to this headline">¶</a></h2>
<p>You can choose either PyQt4 or PySide when using the <codeclass="xref py py-obj docutils literal"><spanclass="pre">qt4</span></code> backend by setting
the appropriate value for <codeclass="xref py py-obj docutils literal"><spanclass="pre">backend.qt4</span></code> in your <codeclass="file docutils literal"><spanclass="pre">matplotlibrc</span></code> file. The
default value is <codeclass="xref py py-obj docutils literal"><spanclass="pre">PyQt4</span></code>.</p>
<p>The setting in your <codeclass="file docutils literal"><spanclass="pre">matplotlibrc</span></code> file can be overridden by setting the
<codeclass="xref py py-obj docutils literal"><spanclass="pre">QT_API</span></code> environment variable to either <codeclass="xref py py-obj docutils literal"><spanclass="pre">pyqt</span></code> or <codeclass="xref py py-obj docutils literal"><spanclass="pre">pyside</span></code> to use <codeclass="xref py py-obj docutils literal"><spanclass="pre">PyQt4</span></code> or
<spanid="interactive-mode"></span><h2>What is interactive mode?<aclass="headerlink" href="#what-is-interactive-mode" title="Permalink to this headline">¶</a></h2>
<p>Use of an interactive backend (see <aclass="reference internal" href="#what-is-a-backend"><span>What is a backend?</span></a>)
permits–but does not by itself require or ensure–plotting
to the screen. Whether and when plotting to the screen occurs,
and whether a script or shell session continues after a plot
is drawn on the screen, depends on the functions and methods
that are called, and on a state variable that determines whether
matplotlib is in “interactive mode”. The default Boolean value is set
by the <codeclass="file docutils literal"><spanclass="pre">matplotlibrc</span></code> file, and may be customized like any other
configuration parameter (see <aclass="reference internal" href="../users/customizing.html#customizing-matplotlib"><span>Customizing matplotlib</span></a>). It
may also be set via <codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.interactive()</span></code>, and its
value may be queried via <codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.is_interactive()</span></code>. Turning
interactive mode on and off in the middle of a stream of plotting
commands, whether in a script or in a shell, is rarely needed
and potentially confusing, so in the following we will assume all
plotting is done with interactive mode either on or off.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Major changes related to interactivity, and in particular the
role and behavior of <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><codeclass="xref py py-func docutils literal"><spanclass="pre">show()</span></code></a>, were made in the
transition to matplotlib version 1.0, and bugs were fixed in
1.0.1. Here we describe the version 1.0.1 behavior for the
primary interactive backends, with the partial exception of
<em>macosx</em>.</p>
</div>
<p>Interactive mode may also be turned on via <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.ion" title="matplotlib.pyplot.ion"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.pyplot.ion()</span></code></a>,
and turned off via <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.ioff" title="matplotlib.pyplot.ioff"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.pyplot.ioff()</span></code></a>.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Interactive mode works with suitable backends in ipython and in
the ordinary python shell, but it does <em>not</em> work in the IDLE IDE.
If the default backend does not support interactivity, an interactive
backend can be explicitly activated using any of the methods discussed in <aclass="reference internal" href="#id3">What is a backend?</a>.</p>
</div>
<divclass="section" id="interactive-example">
<h3>Interactive example<aclass="headerlink" href="#interactive-example" title="Permalink to this headline">¶</a></h3>
<p>From an ordinary python prompt, or after invoking ipython with no options,
<p>and you will see the plot being updated after each line. This is
because you are in interactive mode <em>and</em> you are using pyplot
functions. Now try an alternative method of modifying the
plot. Get a reference to the <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a> instance, and
<p>Nothing changed, because the Axes methods do not include an
automatic call to <codeclass="xref py py-func docutils literal"><spanclass="pre">draw_if_interactive()</span></code>;
that call is added by the pyplot functions. If you are using
methods, then when you want to update the plot on the screen,
you need to call <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.draw" title="matplotlib.pyplot.draw"><codeclass="xref py py-func docutils literal"><spanclass="pre">draw()</span></code></a>:</p>
object method calls in addition to pyplot functions, then
call <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.draw" title="matplotlib.pyplot.draw"><codeclass="xref py py-func docutils literal"><spanclass="pre">draw()</span></code></a> whenever you want to
refresh the plot.</p>
<p>Use non-interactive mode in scripts in which you want to
generate one or more figures and display them before ending
or generating a new set of figures. In that case, use
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><codeclass="xref py py-func docutils literal"><spanclass="pre">show()</span></code></a> to display the figure(s) and
to block execution until you have manually destroyed them.</p>