
Version 2.1.2
Fork me on GitHub


Table Of Contents

This Page

Below we describe several common approaches to plotting with Matplotlib.

The Pyplot API

The matplotlib.pyplot module contains functions that allow you to generate many kinds of plots quickly. For examples that showcase the use of the matplotlib.pyplot module, see the Pyplot tutorial or the Pyplot Examples. We also recommend that you look into the object-oriented approach to plotting, described below.

Function Description
acorr Plot the autocorrelation of x.
angle_spectrum Plot the angle spectrum.
annotate Annotate the point xy with text s.
arrow Add an arrow to the axes.
autoscale Autoscale the axis view to the data (toggle).
axes Add an axes to the figure.
axhline Add a horizontal line across the axis.
axhspan Add a horizontal span (rectangle) across the axis.
axis Convenience method to get or set axis properties.
axvline Add a vertical line across the axes.
axvspan Add a vertical span (rectangle) across the axes.
bar Make a bar plot.
barbs Plot a 2-D field of barbs.
barh Make a horizontal bar plot.
box Turn the axes box on or off.
boxplot Make a box and whisker plot.
broken_barh Plot horizontal bars.
cla Clear the current axes.
clabel Label a contour plot.
clf Clear the current figure.
clim Set the color limits of the current image.
close Close a figure window.
cohere Plot the coherence between x and y.
colorbar Add a colorbar to a plot.
contour Plot contours.
contourf Plot contours.
csd Plot the cross-spectral density.
delaxes Remove an axes from the current figure.
draw Redraw the current figure.
errorbar Plot an errorbar graph.
eventplot Plot identical parallel lines at the given positions.
figimage Adds a non-resampled image to the figure.
figlegend Place a legend in the figure.
figtext Add text to figure.
figure Creates a new figure.
fill Plot filled polygons.
fill_between Make filled polygons between two curves.
fill_betweenx Make filled polygons between two horizontal curves.
findobj Find artist objects.
gcf Get a reference to the current figure.
gci Get the current colorable artist.
get_figlabels Return a list of existing figure labels.
get_fignums Return a list of existing figure numbers.
grid Turn the axes grids on or off.
hexbin Make a hexagonal binning plot.
hist Plot a histogram.
hist2d Make a 2D histogram plot.
hlines Plot horizontal lines at each y from xmin to xmax.
imread Read an image from a file into an array.
imsave Save an array as in image file.
imshow Display an image on the axes.
install_repl_displayhook Install a repl display hook so that any stale figure are automatically redrawn when control is returned to the repl.
ioff Turn interactive mode off.
ion Turn interactive mode on.
isinteractive Return status of interactive mode.
legend Places a legend on the axes.
locator_params Control behavior of tick locators.
magnitude_spectrum Plot the magnitude spectrum.
margins Set or retrieve autoscaling margins.
minorticks_off Remove minor ticks from the current plot.
minorticks_on Display minor ticks on the current plot.
pause Pause for interval seconds.
pcolor Create a pseudocolor plot of a 2-D array.
pcolormesh Plot a quadrilateral mesh.
phase_spectrum Plot the phase spectrum.
pie Plot a pie chart.
plot Plot lines and/or markers to the Axes.
plot_date Plot data that contains dates.
plotfile Plot the data in a file.
polar Make a polar plot.
psd Plot the power spectral density.
quiver Plot a 2-D field of arrows.
quiverkey Add a key to a quiver plot.
rc Set the current rc params.
rc_context Return a context manager for managing rc settings.
rcdefaults Restore the rc params from Matplotlib’s internal defaults.
rgrids Get or set the radial gridlines on a polar plot.
savefig Save the current figure.
sca Set the current Axes instance to ax.
scatter Make a scatter plot of x vs y.
sci Set the current image.
semilogx Make a plot with log scaling on the x axis.
semilogy Make a plot with log scaling on the y axis.
set_cmap Set the default colormap.
setp Set a property on an artist object.
show Display a figure.
specgram Plot a spectrogram.
spy Plot the sparsity pattern on a 2-D array.
stackplot Draws a stacked area plot.
stem Create a stem plot.
step Make a step plot.
streamplot Draws streamlines of a vector flow.
subplot Return a subplot axes at the given grid position.
subplot2grid Create an axis at specific location inside a regular grid.
subplot_tool Launch a subplot tool window for a figure.
subplots Create a figure and a set of subplots This utility wrapper makes it convenient to create common layouts of subplots, including the enclosing figure object, in a single call.
subplots_adjust Tune the subplot layout.
suptitle Add a centered title to the figure.
switch_backend Switch the default backend.
table Add a table to the current axes.
text Add text to the axes.
tick_params Change the appearance of ticks and tick labels.
ticklabel_format Change the ScalarFormatter used by default for linear axes.
tight_layout Automatically adjust subplot parameters to give specified padding.
title Set a title of the current axes.
tricontour Draw contours on an unstructured triangular grid.
tricontourf Draw contours on an unstructured triangular grid.
tripcolor Create a pseudocolor plot of an unstructured triangular grid.
twinx Make a second axes that shares the x-axis.
twiny Make a second axes that shares the y-axis.
uninstall_repl_displayhook Uninstalls the matplotlib display hook.
violinplot Make a violin plot.
vlines Plot vertical lines.
xcorr Plot the cross correlation between x and y.
xkcd Turns on xkcd sketch-style drawing mode.
xlabel Set the x axis label of the current axis.
xlim Get or set the x limits of the current axes.
xscale Set the scaling of the x-axis.
ylabel Set the y axis label of the current axis.
yscale Set the scaling of the y-axis.

The Object-Oriented API

Most of these functions also exist as methods in the matplotlib.axes.Axes class. You can use them with the “Object Oriented” approach to Matplotlib.

While it is easy to quickly generate plots with the matplotlib.pyplot module, we recommend using the object-oriented approach for more control and customization of your plots. See the methods in the matplotlib.axes.Axes() class for many of the same plotting functions. For examples of the OO approach to Matplotlib, see the API Examples.

Colors in Matplotlib

There are many colormaps you can use to map data onto color values. Below we list several ways in which color can be utilized in Matplotlib.

For a more in-depth look at colormaps, see the Colormaps in Matplotlib tutorial.





or using the set_cmap() function:




There are several common color schemes used in visualization:

Sequential schemes
for unipolar data that progresses from low to high
Diverging schemes
Cyclic schemes
Qualitative schemes

Matplotlib ships with 4 perceptually uniform color maps which are the recommended color maps for sequential data:

Colormap Description
inferno perceptually uniform shades of black-red-yellow
magma perceptually uniform shades of black-red-white
plasma perceptually uniform shades of blue-red-yellow
viridis perceptually uniform shades of blue-green-yellow



Colormap Description
BrBG brown, white, blue-green
PiYG pink, white, yellow-green
PRGn purple, white, green
PuOr orange, white, purple
RdBu red, white, blue
RdGy red, white, gray
RdYlBu red, yellow, blue
RdYlGn red, yellow, green
Spectral red, orange, yellow, green, blue

ColorBrewer Sequential (luminance decreases monotonically):

Colormap Description
Blues white to dark blue
BuGn white, light blue, dark green
BuPu white, light blue, dark purple
GnBu white, light green, dark blue
Greens white to dark green
Greys white to black (not linear)
Oranges white, orange, dark brown
OrRd white, orange, dark red
PuBu white, light purple, dark blue
PuBuGn white, light purple, dark green
PuRd white, light purple, dark red
Purples white to dark purple
RdPu white, pink, dark purple
Reds white to dark red
YlGn light yellow, dark green
YlGnBu light yellow, light green, dark blue
YlOrBr light yellow, orange, dark brown
YlOrRd light yellow, orange, dark red

ColorBrewer Qualitative:

(For plotting nominal data, ListedColormap is used, not LinearSegmentedColormap. Different sets of colors are recommended for different numbers of categories.)

  • Accent
  • Dark2
  • Paired
  • Pastel1
  • Pastel2
  • Set1
  • Set2
  • Set3

A set of colormaps derived from those of the same name provided with Matlab are also included:

Colormap Description
autumn sequential linearly-increasing shades of red-orange-yellow
cool linearly-decreasing shades of cyan-magenta
copper sequential increasing shades of black-copper
gray sequential linearly-increasing black-to-white grayscale
prism repetitive red-yellow-green-blue-purple-…-green pattern (not cyclic at endpoints)
spring linearly-increasing shades of magenta-yellow
summer sequential linearly-increasing shades of green-yellow
winter linearly-increasing shades of blue-green

A set of palettes from the Yorick scientific visualisation package, an evolution of the GIST package, both by David H. Munro are included:

Colormap Description
gist_stern “Stern special” color table from Interactive Data Language software

Other miscellaneous schemes:

Colormap Description
brg blue-red-green
bwr diverging blue-white-red
ocean green-blue-white
seismic diverging blue-white-red


Colormap Description
gist_gray identical to gray
gist_yarg identical to gray_r
binary identical to gray_r
spectral identical to nipy_spectral [5]

