IPython integration#

We recommend using IPython for an interactive shell. In addition toall of its features (improved tab-completion, magics, multiline editing, etc),it also ensures that the GUI toolkit event loop is properly integratedwith the command line (seeCommand prompt integration).

In this example, we create and modify a figure via an IPython prompt.The figure displays in a QtAgg GUI window. To configure the integrationand enableinteractive mode use the%matplotlib magic:

In [1]:%matplotlibUsing matplotlib backend: QtAggIn [2]:importmatplotlib.pyplotasplt

Create a new figure window:

In [3]:fig,ax=plt.subplots()

Add a line plot of the data to the window:

In [4]:ln,=ax.plot(range(5))

Change the color of the line from blue to orange:

In [5]:ln.set_color('orange')

If you wish to disable automatic redrawing of the plot:

In [6]:plt.ioff()

If you wish to re-enable automatic redrawing of the plot:

In [7]:plt.ion()

In recent versions ofMatplotlib andIPython, it issufficient to importmatplotlib.pyplot and callpyplot.ion.Using the% magic is guaranteed to work in all versions of Matplotlib and IPython.

Interactive mode#

Interactive mode controls:

• whether created figures are automatically shown

• whether changes to artists automatically trigger re-drawing existing figures

• whenpyplot.show() returns if given no arguments: immediately, or after all of the figures have been closed

If in interactive mode:

• newly created figures will be displayed immediately

• figures will automatically redraw when elements are changed

• pyplot.show() displays the figures and immediately returns

If not in interactive mode:

• newly created figures and changes to figures are not displayed until

  • pyplot.show() is called

  • pyplot.pause() is called

  • FigureCanvasBase.flush_events() is called

• pyplot.show() runs the GUI event loop and does not return until all the plot windows are closed

If you are in non-interactive mode (or created figures while innon-interactive mode) you may need to explicitly callpyplot.showto display the windows on your screen. If you only want to run theGUI event loop for a fixed amount of time, you can usepyplot.pause.This will block the progress of your code as if you had calledtime.sleep, ensure the current window is shown and re-drawn if needed,and run the GUI event loop for the specified period of time.

The GUI event loop being integrated with your command prompt andthe figures being in interactive mode are independent of each other.If you try to usepyplot.ion 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 thedesktop under it). Conversely, if you configure the event loopintegration, displayed figures will be responsive while waiting for inputat the prompt, regardless of pyplot's "interactive mode".

No matter what combination of interactive mode setting and event loop integration,figures will be responsive if you usepyplot.show(block=True),pyplot.pause, or runthe GUI main loop in some other way.

Default UI#

The windows created bypyplot have an interactive toolbar with navigationbuttons and a readout of the data values the cursor is pointing at.

Interactive navigation#

All figure windows come with a navigation toolbar, which can be usedto navigate through the data set.

TheHome,Forward andBack buttons

These are similar to a web browser's home, forward and back controls.Forward andBack are used to navigate back and forth betweenpreviously defined views. They have no meaning unless you have alreadynavigated somewhere else using the pan and zoom buttons. This is analogousto trying to clickBack on your web browser before visiting anew page orForward before you have gone back to a page --nothing happens.Home takes you to thefirst, default view of your data.

ThePan/Zoom button

This button has two modes: pan and zoom. Click thePan/Zoom buttonto activate panning and zooming, then put your mouse somewhereover an axes. Press the left mouse button and hold it to pan thefigure, dragging it to a new position. When you release it, thedata under the point where you pressed will be moved to the pointwhere you released. If you press 'x' or 'y' while panning themotion will be constrained to the x or y axis, respectively. Pressthe right mouse button to zoom, dragging it to a new position.The x axis will be zoomed in proportionately to the rightwardmovement and zoomed out proportionately to the leftward movement.The same is true for the y axis and up/down motions (up zooms in, down zooms out).The point under your mouse when you begin the zoom remains stationary, allowing you tozoom in or out around that point as much as you wish. You can use themodifier keys 'x', 'y' or 'CONTROL' to constrain the zoom to the xaxis, the y axis, or aspect ratio preserve, respectively.

With polar plots, the pan and zoom functionality behavesdifferently. The radius axis labels can be dragged using the leftmouse button. The radius scale can be zoomed in and out using theright mouse button.

TheZoom-to-Rectangle button

Put your mouse somewhere over an axes and press a mouse button. Define a rectangular region bydragging the mouse while holding the button to a new location. When usingthe left mouse button, the axes view limits will be zoomed to the definedregion. When using the right mouse button, the axes view limits will bezoomed out, placing the original axes in the defined region.

TheSubplot-configuration button

Use this button to configure the appearance of the subplot.You can stretch or compress the left, right, top, or bottomside of the subplot, or the space between the rows orspace between the columns.

TheSave button

Click this button to launch a file save dialog. You can savefiles with the following extensions:png,ps,eps,svg andpdf.

Other Python prompts#

Interactive mode works in the default Python prompt:

>>>importmatplotlib.pyplotasplt>>>plt.ion()>>>

However, this does not ensure that the event hook is properly installedand your figures may not be responsive. Please consult thedocumentation of your GUI toolkit for details.

%matplotlib widget

%matplotlib notebook