Table Of Contents

Previous topic

matplotlib collections

Next topic

matplotlib colors

This Page

matplotlib colorbar


Colorbar toolkit with two classes and a function:

the base class with full colorbar drawing functionality. It can be used as-is to make a colorbar for a given colormap; a mappable object (e.g., image) is not needed.
the derived class for use with images or contour plots.
a function for resizing an axes and adding a second axes suitable for a colorbar

The colorbar() method uses make_axes() and Colorbar; the colorbar() function is a thin wrapper over colorbar().

class matplotlib.colorbar.Colorbar(ax, mappable, **kw)

Bases: matplotlib.colorbar.ColorbarBase

This class connects a ColorbarBase to a ScalarMappable such as a AxesImage generated via imshow().

It is not intended to be instantiated directly; instead, use colorbar() or colorbar() to make your colorbar.


Add the lines from a non-filled ContourSet to the colorbar.


Destroy and rebuild the colorbar. This is intended to become obsolete, and will probably be deprecated and then removed. It is not called when the pyplot.colorbar function or the Figure.colorbar method are used to create the colorbar.


update solid, lines, etc. Unlike update_bruteforce, it does not clear the axes. This is meant to be called when the image or contour plot to which this colorbar belongs is changed.

class matplotlib.colorbar.ColorbarBase(ax, cmap=None, norm=None, alpha=None, values=None, boundaries=None, orientation='vertical', extend='neither', spacing='uniform', ticks=None, format=None, drawedges=False, filled=True)


Draw a colorbar in an existing axes.

This is a base class for the Colorbar class, which is the basis for the colorbar() function and the colorbar() method, which are the usual ways of creating a colorbar.

It is also useful by itself for showing a colormap. If the cmap kwarg is given but boundaries and values are left as None, then the colormap will be displayed on a 0-1 scale. To show the under- and over-value colors, specify the norm as:


To show the colors versus index instead of on the 0-1 scale, use:


Useful attributes:

the Axes instance in which the colorbar is drawn
a LineCollection if lines were drawn, otherwise None
a LineCollection if drawedges is True, otherwise None

Useful public methods are set_label() and add_lines().

add_lines(levels, colors, linewidths)

Draw lines on the colorbar.


Calculate any free parameters based on the current cmap and norm, and do all the drawing.

set_label(label, **kw)

Label the long axis of the colorbar

set_ticklabels(ticklabels, update_ticks=True)

set tick labels. Tick labels are updated immediately unless update_ticks is False. To manually update the ticks, call update_ticks method explicitly.

set_ticks(ticks, update_ticks=True)

set tick locations. Tick locations are updated immediately unless update_ticks is False. To manually update the ticks, call update_ticks method explicitly.


Force the update of the ticks and ticklabels. This must be called whenever the tick locator and/or tick formatter changes.

matplotlib.colorbar.make_axes(parent, **kw)

Resize and reposition a parent axes, and return a child axes suitable for a colorbar:

cax, kw = make_axes(parent, **kw)

Keyword arguments may include the following (with defaults):

‘vertical’ or ‘horizontal’
Property Description
orientation vertical or horizontal
fraction 0.15; fraction of original axes to use for colorbar
pad 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes
shrink 1.0; fraction by which to shrink the colorbar
aspect 20; ratio of long to short dimensions

All but the first of these are stripped from the input kw set.

Returns (cax, kw), the child axes and the reduced kw dictionary.