Configuring proplot


A special object named rc, belonging to the rc_configurator class, is created on import. This is your one-stop shop for changing global settings belonging to any of the following three categories.

  1. Builtin matplotlib rcParams settings. These have the format x.y or x.y.z.

  2. ProPlot rcParamsLong settings. These also have the format x.y (see below).

  3. ProPlot rcParamsShort settings. These have no dots (see below).

You can change settings with the rc object as follows.

  • = value

  • plot.rc['name'] = value

  • plot.rc.update(name1=value1, name2=value2)

  • plot.rc.update({'name1':value1, 'name2':value2})

To temporarily change settings on a particular axes, use either of the following.

  • ax.format(name=value)

  • ax.format(rc_kw={'name':value})

In all of these examples, if the setting name name contains any dots, you can simply omit the dots. For example, to change the rc[‘title.loc’] property, use plot.rc.titleloc = value, plot.rc.update(titleloc=value), or ax.format(titleloc=value).


These are simple, short names used to change multiple matplotlib and ProPlot settings at once, as shorthands for settings with longer names, or for special options. For example, rc.ticklen changes the tick length for the x and y axes in one go.




Boolean, whether to draw a-b-c labels by default.


Whether to align axis labels during draw. See aligning labels.


The opacity of the background axes patch.


If not empty or 0, passed to %autoreload.


If not empty or 0, passed to %autosave.


Boolean, toggles country border lines on and off.


The default colormap.


Boolean, toggles coastline lines on and off.


The color of axis spines, tick marks, tick labels, and labels.


The default color cycle name, used e.g. for lines.


The color of the background axes patch.


Name of font used for all text in the figure. The default is Helvetica Neue. See fonttools for details.


Boolean, toggles meridian and parallel gridlines on and off.


Boolean, toggles major grid lines on and off.


Boolean, toggles minor grid lines on and off.


Ratio of minor gridline width to major gridline width.


The inline backend figure format or list thereof. Valid formats include 'svg', 'pdf', 'retina', 'png', and jpeg.


Boolean, toggles internal border lines on and off, e.g. for states and provinces.


Boolean, toggles lake patches on and off.


Boolean, toggles land patches on and off.


Font size for titles, “super” titles, and a-b-c subplot labels.


Thickness of axes spines and major tick lines.


The number of colors to put in the colormap lookup table.


The margin of space between axes edges and objects plotted inside the axes, if xlim and ylim are unset.


If not empty, passed to %matplotlib. If 'auto' (the default) uses 'inline' for notebooks and 'osx' or 'qt' for other ipython sessions.


Boolean, toggles ocean patches on and off.


Resolution of geographic features, one of 'lo', 'med', or 'hi'


If True, and colorblind is the current cycle, this registers the colorblind colors as 'r', 'b', 'g', etc., like in seaborn.


Boolean, toggles river lines on and off.


The axis sharing level, one of 0, 1, 2, or 3. See subplots for details.


Font size for legend text, tick labels, axis labels, and text generated with text.


Boolean, toggles spanning axis labels. See subplots for details.


Major and minor tick direction. Must be one of out, in, or inout.


Length of major ticks in points.


Ratio of minor tickline length to major tickline length.


Padding between ticks and tick labels in points.


Padding between the axes and the title, alias for rc[‘axes.titlepad’].


Ratio of minor tickline width to major tickline width.


Boolean, indicates whether to auto-adjust figure bounds and subplot spacings.


These are longer, specific setting names used to customize things not covered by rcParams.

The subplots category controls the default layout for figures and axes. The abc, title, and tick categories control a-b-c label, title, and axis tick label settings. The suptitle, leftlabel, toplabel, rightlabel, and bottomlabel categories control figure title and edge label settings.

There are two new additions to the image category, and the new colorbar category controls inset and outer colorbar properties. The new gridminor category controls minor gridline settings, and the new geogrid category controls meridian and parallel line settings for ProjAxes. For both gridminor and geogrid, if a property is empty, the corresponding property from grid is used.

Finally, the geoaxes, land, ocean, rivers, lakes, borders, and innerborders categories control various ProjAxes settings. These are used when the boolean toggles for the corresponding rcParamsShort settings are turned on.



a-b-c label style. For options, see format.


a-b-c label position. For options, see format.


Boolean, indicates whether to draw a white border around a-b-c labels inside an axes.


Width of the white border around a-b-c labels.

abc.color, abc.size, abc.weight

Font color, size, and weight for a-b-c labels.


Boolean, indicates whether trailing decimal zeros are trimmed on tick labels.


Float, indicates the default x axis tick label rotation for datetime tick labels.

borders.color, borders.linewidth

Line color and linewidth for country border lines.

bottomlabel.color, bottomlabel.size, bottomlabel.weight

Font color, size, and weight for column labels on the bottom of the figure.


Inset colorbar location, options are listed in colorbar.


Boolean, indicates whether to draw borders between each level of the colorbar.


Boolean, indicates whether to draw a frame behind inset colorbars.


Opacity for inset colorbar frames.


Length of outer colorbars.


Length of inset colorbars. Units are interpreted by units.


Width of outer colorbars. Units are interpreted by units.


Width of inset colorbars. Units are interpreted by units.


Padding between axes edge and inset colorbars. Units are interpreted by units.


Length of rectangular or triangular “extensions” for panel colorbars. Units are interpreted by units.


Length of rectangular or triangular “extensions” for inset colorbars. Units are interpreted by units.

geoaxes.facecolor, geoaxes.edgecolor, geoaxes.linewidth

Face color, edge color, and edge width for the map outline patch.


Boolean, indicates whether to label the parallels and meridians.


Font size for latitude and longitude labels. Inherits from small.


Absolute latitude in degrees, poleward of which meridian gridlines are cut off.

geogrid.lonstep, geogrid.latstep

Interval for meridian and parallel gridlines, in degrees.

gridminor.linewidth, geogrid.linewidth

The line width.

gridminor.linestyle, geogrid.linestyle

The line style.

gridminor.alpha, geogrid.alpha

The line transparency.

gridminor.color, geogrid.color

The line color.


Default number of levels for pcolormesh and contourf plots.


Whether to fix the white-lines-between-filled-contours and white-lines-between-pcolor-rectangles issues. This slows down figure rendering a bit.

innerborders.color, innerborders.linewidth

Line color and linewidth for internal border lines.

land.color, ocean.color, lakes.color

Face color for land, ocean, and lake patches.

leftlabel.color, leftlabel.size, leftlabel.weight

Font color, size, and weight for row labels on the left-hand side.

rightlabel.color, rightlabel.size, rightlabel.weight

Font color, size, and weight for row labels on the right-hand side.

rivers.color, rivers.linewidth

Line color and linewidth for river lines.


Default width of each axes. Units are interpreted by units.


Width of side panels. Units are interpreted by units.


Padding around figure edge. Units are interpreted by units.


Padding between adjacent subplots. Units are interpreted by units.


Padding between subplots and panels, and between stacked panels. Units are interpreted by units.


Vertical space for titles. Units are interpreted by units.


Horizontal space between subplots allotted for y-labels. Units are interpreted by units.


Vertical space between subplots allotted for x-labels. Units are interpreted by units.


Space between subplots allotted for tick marks. Units are interpreted by units.


Purely empty space between main axes and side panels. Units are interpreted by units.

suptitle.color, suptitle.size, suptitle.weight

Font color, size, and weight for the figure title.

tick.labelcolor, tick.labelsize, tick.labelweight

Font color, size, and weight for axis tick labels. These mirror the axes.labelcolor, axes.labelsize, and axes.labelweight rcParams settings used for axes labels.


Title position. For options, see format.


Boolean, indicates whether to draw a white border around titles inside an axes.


Width of the white border around titles.


Alias for axes.titlepad, the title offset in arbitrary units

title.color, title.size, title.weight

Font color, size, and weight for subplot titles.

toplabel.color, toplabel.size, toplabel.weight

Font color, size, and weight for column labels on the top of the figure.

proplotrc file

To modify the global settings, edit your ~/.proplotrc file. To modify settings for a particular project, create a .proplotrc file in the same directory as your ipython notebook, or in an arbitrary parent directory.

As an example, the default .proplotrc file is shown below. The syntax is roughly the same as that used for matplotlibrc files, although .proplotrc strictly adheres to YAML.

# rcParamsShort defaults
abc:          False
align:        False
alpha:        1
autoreload:   2
autosave:     30
borders:      False
cmap:         fire
coast:        False
color:        k
cycle:        colorblind
facecolor:    w
fontname:     'Helvetica Neue'
geogrid:      True
grid:         True
gridminor:    False
gridratio:    0.5
inlinefmt:    retina
innerborders: False
lakes:        False
land:         False
large:        10
linewidth:    0.6
lut:          256
margin:       0.0
matplotlib:   auto
ocean:        False
reso:         lo
rgbcycle:     False
rivers:       False
share:        3
small:        9
span:         True
tickdir:      out
ticklen:      4.0
ticklenratio: 0.5
tickpad:      2.0
tickratio:    0.8
tight:        True

# rcParamsLong defaults
abc.border:                  True
abc.color:                   k
abc.linewidth:               1.5
abc.loc:                     l
abc.size:                    # filled by 'large'                   a
abc.weight:                  bold
axes.alpha:                  # if empty, depends on 'savefig.transparent' setting
axes.formatter.timerotation: 90
axes.formatter.zerotrim:     True
axes.geogrid:                True
axes.gridminor:              True
borders.color:               k
borders.linewidth:           0.6
bottomlabel.color:           k
bottomlabel.size:            # filled by 'large'
bottomlabel.weight:          bold
coast.color:                 k
coast.linewidth:             0.6
colorbar.axespad:            0.5em
colorbar.extend:             1.3em
colorbar.framealpha:         0.8
colorbar.frameon:            True
colorbar.grid:               False
colorbar.insetextend:        1em
colorbar.insetlength:        8em
colorbar.insetwidth:         1.2em
colorbar.length:             1
colorbar.loc:                right
colorbar.width:              1.5em
geoaxes.edgecolor:           # filled by "color"
geoaxes.facecolor:           # filled by "facecolor"
geoaxes.linewidth:           # filled by "linewidth"
geogrid.alpha:               0.5
geogrid.color:               k
geogrid.labels:              False
geogrid.labelsize:           # filled by "small"
geogrid.latmax:              90
geogrid.latstep:             20
geogrid.linestyle:           ':'
geogrid.linewidth:           1.0
geogrid.lonstep:             30
gridminor.alpha:             # filled by "grid.alpha"
gridminor.color:             # filled by "grid.color"
gridminor.linestyle:         # filled by "grid.linewidth"
gridminor.linewidth:         # filled by "grid.linewidth" x "gridratio"
image.edgefix:               True
image.levels:                11
innerborders.color:          k
innerborders.linewidth:      0.6
lakes.color:                 w
land.color:                  k
leftlabel.color:             k
leftlabel.size:              # filled by 'large'
leftlabel.weight:            bold
ocean.color:                 w
rightlabel.color:            k
rightlabel.size:             # filled by 'large'
rightlabel.weight:           bold
rivers.color:                k
rivers.linewidth:            0.6
subplots.axpad:              1em
subplots.axwidth:            18em  # 2 inches
subplots.innerspace:         1.5em
subplots.pad:                0.5em
subplots.panelpad:           0.5em
subplots.panelspace:         1em
subplots.panelwidth:         4em   # 0.45 inches
subplots.titlespace:         2em
subplots.xlabspace:          4em
subplots.ylabspace:          5.5em
suptitle.color:              k
suptitle.size:               # filled by 'large'
suptitle.weight:             bold
tick.labelcolor:             # filled by 'color'
tick.labelsize:              # filled by 'small'
tick.labelweight:            normal
title.border:                True
title.color:                 k
title.linewidth:             1.5
title.loc:                   c # centered above the axes
title.pad:                   3.0 # copy
title.size:                  # filled by 'large'
title.weight:                normal
toplabel.color:              k
toplabel.size:               # filled by 'large'
toplabel.weight:             bold

# rcParams defaults
# See:
axes.labelpad:        3.0
axes.titlepad:        3.0
figure.autolayout:    False
figure.facecolor:     '#f2f2f2'
grid.alpha:           0.1
grid.color:           'k'
grid.linestyle:       '-'
grid.linewidth:       0.6
hatch.color:          k
hatch.linewidth:      0.6
legend.borderaxespad: 0
legend.columnspacing: 1.0
legend.fancybox:      False
legend.handletextpad: 0.5
lines.linewidth:      1.3
lines.markersize:     3.0
mathtext.default:     regular
savefig.bbox:         standard
savefig.dpi:          300
savefig.format:       pdf
savefig.pad_inches:   0.0
savefig.transparent:  True
xtick.minor.visible:  True
ytick.minor.visible:  True