API reference

The comprehensive API reference. All of the below objects are imported into the top-level namespace. Use help(pplt.object) to read the docs during a python session.

Please note that the documentation of plotting command “wrappers” from ProPlot < 0.8 is now found in the individual PlotAxes plotting commands. Using help(ax.command) during a python session shows both the ProPlot documentation and the original matplotlib documentation.

Figure class

The figure class used for all ProPlot figures.

Figure(*[, refnum, ref, refaspect, aspect, ...])

The Figure subclass used by proplot.


List-like object used to store subplots returned by subplots.

Gridspec class

The gridspec and subplotspec subclasses.

GridSpec([nrows, ncols])

A GridSpec subclass that permits variable spacing between successive rows and columns and hides "panel slots" from indexing.

Axes classes

The axes classes used for all ProPlot figures.

Axes(*args, **kwargs)

The lowest-level Axes subclass used by proplot.

PlotAxes(*args, **kwargs)

The second lowest-level Axes subclass used by proplot.

CartesianAxes(*args, **kwargs)

Axes subclass for plotting in ordinary Cartesian coordinates.

PolarAxes(*args, **kwargs)

Axes subclass for plotting in polar coordinates.

GeoAxes(*args, **kwargs)

Axes subclass for plotting in geographic projections.

ThreeAxes(*args, **kwargs)

Simple mix-in of proplot.axes.PlotAxes with Axes3D.

Top-level functions

The starting point for creating ProPlot figures.

figure(*args, **kwargs)

Create an empty figure.

subplots(*args, **kwargs)

Create a figure with a single subplot or an arbitrary grid of subplots.

show(*args, **kwargs)

Call matplotlib.pyplot.show.

close(*args, **kwargs)

Call matplotlib.pyplot.close.

switch_backend(*args, **kwargs)

Call matplotlib.pyplot.switch_backend.


Call matplotlib.pyplot.ion.


Call matplotlib.pyplot.ioff.


Call matplotlib.pyplot.isinteractive.

Configuration tools

Tools for setting up ProPlot and configuring global settings. See the configuration guide for details.

Configurator([local, user, default])

A dictionary-like class for managing matplotlib settings stored in rc_matplotlib and ProPlot settings stored in rc_proplot.


Instance of Configurator.


A dictionary-like container of ProPlot settings.


A dictionary-like container of matplotlib settings.


Apply the matplotlib style(s) with matplotlib.style.use.


Set up the ipython inline backend display format and ensure that inline figures always look the same as saved figures.

register_cmaps(*args[, user, default])

Register named colormaps.

register_cycles(*args[, user, default])

Register named color cycles.

register_colors(*args[, user, default, ...])

Register named colors.

register_fonts(*args[, user, default])

Register font names.

Constructor functions

The constructor functions used to build class instances from simple shorthand arguments.

Proj(name[, basemap])

Return a cartopy.crs.Projection or Basemap instance.

Locator(locator, *args, **kwargs)

Return a Locator instance.

Formatter(formatter, *args[, date, index])

Return a Formatter instance.

Scale(scale, *args, **kwargs)

Return a ScaleBase instance.

Colormap(*args[, name, listmode, filemode, ...])

Generate, retrieve, modify, and/or merge instances of PerceptualColormap, ContinuousColormap, and DiscreteColormap.

Norm(norm, *args, **kwargs)

Return an arbitrary Normalize instance.

Cycle(*args[, N, samples, name])

Generate and merge Cycler instances in a variety of ways.

Locators and formatters

Various Locator and Formatter classes.

AutoFormatter([zerotrim, tickrange, ...])

The new default number formatter.

FracFormatter([symbol, number])

Format numbers as fractions or multiples of some value.

LongitudeLocator(*args, **kwargs)

A locator for longitude gridlines.

LatitudeLocator(*args, **kwargs)

A locator for latitude gridlines.

SciFormatter([precision, zerotrim])

Format numbers with scientific notation.

SigFigFormatter([sigfig, zerotrim])

Format numbers by retaining the specified number of significant digits.

SimpleFormatter([precision, zerotrim, ...])

A general purpose number formatter.

Axis scale classes

Various axis ScaleBase classes.


Axis scale composed of arbitrary piecewise linear transformations.

ExpScale([a, b, c, inverse])

"Exponential scale" that performs either of two transformations.

FuncScale(arg[, invert, parent_scale, ...])

Axis scale composed of arbitrary forward and inverse transformations.


Axis scale that is linear in the inverse of x.


As with LinearScale but with AutoFormatter as the default major formatter.


As with LogitScale but with AutoFormatter as the default major formatter.


As with LogScale but with AutoFormatter as the default major formatter.


Axis scale that is linear in the Mercator projection latitude.

PowerScale([power, inverse])

"Power scale" that performs the transformation


Axis scale that is linear in the sine transformation of x.


As with SymmetricalLogScale but with AutoFormatter as the default major formatter.

Colormaps and normalizers

New colormap classes and colormap normalization classes.

DiscreteColormap(colors[, name, N, alpha])

Replacement for ListedColormap.

ContinuousColormap(*args[, gamma, cyclic, alpha])

Replacement for LinearSegmentedColormap.

PerceptualColormap(*args[, space, clip, ...])

A ContinuousColormap with linear transitions across hue, saturation, and luminance rather than red, blue, and green.

DiscreteNorm(levels[, norm, unique, step, ...])

Meta-normalizer that discretizes the possible color values returned by arbitrary continuous normalizers given a list of level boundaries.

DivergingNorm([vcenter, vmin, vmax, fair, clip])

Normalizer that ensures some central data value lies at the central colormap color.

SegmentedNorm(levels[, vmin, vmax, clip])

Normalizer that scales data linearly with respect to the interpolated list index in an arbitrary monotonically increasing level list.


Dictionary subclass used to replace the builtin matplotlib color database.


Dictionary subclass used to replace the matplotlib colormap registry.

Projection classes

Additional cartopy projection classes.

Aitoff([central_longitude, globe, ...])

The Aitoff projection.

Hammer([central_longitude, globe, ...])

The Hammer projection.

KavrayskiyVII([central_longitude, globe, ...])

The Kavrayskiy VII projection.

WinkelTripel([central_longitude, globe, ...])

The Winkel tripel (Winkel III) projection.


Analogous to NorthPolarStereo.


Analogous to SouthPolarStereo.

NorthPolarGnomonic([central_longitude, globe])

Analogous to NorthPolarStereo.

SouthPolarGnomonic([central_longitude, globe])

Analogous to SouthPolarStereo.


Analogous to NorthPolarStereo.


Analogous to SouthPolarStereo.

Miscellaneous tools

Various tools that may be useful while making plots.

arange(min_, *args)

Identical to numpy.arange but with inclusive endpoints.

edges(z[, axis])

Calculate the approximate "edge" values along an axis given "center" values.


Calculate the approximate "edge" values given a 2d grid of "center" values.

get_colors(*args, **kwargs)

Get the colors associated with a registered or on-the-fly color cycle.

set_hue(color, hue[, space])

Return a color with a different hue and the same luminance and saturation as the input color.

set_saturation(color, saturation[, space])

Return a color with a different saturation and the same hue and luminance as the input color.

set_luminance(color, luminance[, space])

Return a color with a different luminance and the same hue and saturation as the input color.

set_alpha(color, alpha)

Return a color with the opacity channel set to the specified value.

shift_hue(color[, shift, space])

Shift the hue channel of a color.

scale_saturation(color[, scale, space])

Scale the saturation channel of a color.

scale_luminance(color[, scale, space])

Scale the luminance channel of a color.

to_hex(color[, space, cycle, keep_alpha])

Translate the color in any format and from any colorspace to a HEX string.

to_rgb(color[, space, cycle])

Translate the color in any format and from any colorspace to an RGB tuple.

to_xyz(color[, space])

Translate color in any format to a tuple of channel values in any colorspace.

to_rgba(color[, space, cycle])

Translate the color in any format and from any colorspace to an RGB tuple.

to_xyza(color[, space])

Translate color in any format to a tuple of channel values in any colorspace.

units(value[, numeric, dest, fontsize, ...])

Convert values and lists of values between arbitrary physical units.

Demo functions

Functions for displaying colors and fonts.

show_cmaps(*args, **kwargs)

Generate a table of the registered colormaps or the input colormaps categorized by source.

show_channels(*args[, N, saturation, rgb, ...])

Show how arbitrary colormap(s) vary with respect to the hue, chroma, luminance, HSL saturation, and HPL saturation channels, and optionally the red, blue and green channels.

show_colors(*[, nhues, minsat, unknown, ...])

Generate tables of the registered color names.

show_colorspaces(*[, luminance, saturation, ...])

Generate hue-saturation, hue-luminance, and luminance-saturation cross-sections for the HCL, HSL, and HPL colorspaces.

show_cycles(*args, **kwargs)

Generate a table of registered color cycles or the input color cycles categorized by source.

show_fonts(*args[, family, text, size, ...])

Generate a table of fonts.