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 proplot removes the associated documentation when functionality is deprecated (see What’s New). However, proplot adheres to semantic versioning, which means old code that uses deprecated functionality will still work and issue warnings rather than errors until the first major release (version 1.0.0).


The documentation for “wrapper” functions like standardize_1d and cmap_changer from proplot < 0.8.0 can now be found under individual PlotAxes methods like plot and pcolor. Note that calling help(ax.method) in a python session will show both the proplot documentation and the original matplotlib documentation.

Figure class

The figure class used for all proplot figures.


The Figure subclass used by proplot.

Grid classes

The gridspec and subplot grid classes used throughout proplot.

GridSpec([nrows, ncols])

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


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

Axes classes

The various axes classes used throughout proplot.

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.Axes with Axes3D.

Top-level functions

The starting point for creating proplot figures.


Create an empty figure.


Return a figure and a single subplot.

subplots(*args, **kwargs)

Return a figure and 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, local, default])

Register named colormaps.

register_cycles(*args[, user, local, default])

Register named color cycles.

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

Register named colors.

register_fonts(*args[, user, local, default])

Register font families.

Constructor functions

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

Proj(name[, backend, lon0, lon_0, lat0, ...])

Return a cartopy.crs.Projection or Basemap instance.

Locator(locator, *args[, discrete])

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.

IndexLocator([base, offset])

Format numbers by assigning fixed strings to non-negative indices.

DiscreteLocator(locs, **kwargs)

A tick locator suitable for discretized colorbars.

DegreeLocator(*args, **kwargs)

Locate geographic gridlines with degree-minute-second support.

LongitudeLocator(*args, **kwargs)

Locate longitude gridlines with degree-minute-second support.

LatitudeLocator(*args, **kwargs)

Locate latitude gridlines with degree-minute-second support.

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

The default formatter used for proplot tick labels.

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

A general purpose number formatter.


Format numbers by assigning fixed strings to non-negative indices.

SciFormatter([precision, zerotrim])

Format numbers with scientific notation.

SigFigFormatter([sigfig, zerotrim, base])

Format numbers by retaining the specified number of significant digits.

FracFormatter([symbol, number])

Format numbers as integers or integer fractions.

DegreeFormatter(*args, **kwargs)

Formatter for longitude and latitude gridline labels.

LongitudeFormatter(*args, **kwargs)

Format longitude gridline labels.

LatitudeFormatter(*args, **kwargs)

Format latitude gridline labels.

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([transform, 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

Various colormap classes and colormap normalization classes.

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

Replacement for ListedColormap.

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

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 sequence of level boundaries.

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

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

SegmentedNorm(levels[, vcenter, vmin, vmax, ...])

Normalizer that scales data linearly with respect to the interpolated index in an arbitrary monotonic level sequence.


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.

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, rgb, saturation, ...])

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, user, text, ...])

Generate a table of fonts.

Miscellaneous functions

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 or colormap.

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 from an arbitrary colorspace to a HEX string.

to_rgb(color[, space, cycle])

Translate the color from an arbitrary 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, clip])

Translate the color from an arbitrary colorspace to an RGBA 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 between arbitrary physical units.