You are reading an old version of the documentation (v3.0.2). For the latest version see
Version 3.0.2
Fork me on GitHub

Table of Contents


Axes.clabel(CS, *args, **kwargs)[source]

Label a contour plot.

Call signature:

clabel(cs, [levels,] **kwargs)

Adds labels to line contours in cs, where cs is a ContourSet object returned by contour().

cs : ContourSet

The ContourSet to label.

levels : array-like, optional

A list of level values, that should be labeled. The list must be a subset of cs.levels. If not given, all levels are labeled.

fontsize : string or float, optional

Size in points or relative size e.g., 'smaller', 'x-large'. See Text.set_size for accepted string values.

colors : color-spec, optional

The label colors:

  • If None, the color of each label matches the color of the corresponding contour.
  • If one string color, e.g., colors = 'r' or colors = 'red', all labels will be plotted in this color.
  • If a tuple of matplotlib color args (string, float, rgb, etc), different labels will be plotted in different colors in the order specified.
inline : bool, optional

If True the underlying contour is removed where the label is placed. Default is True.

inline_spacing : float, optional

Space in pixels to leave on each side of label when placing inline. Defaults to 5.

This spacing will be exact for labels at locations where the contour is straight, less so for labels on curved contours.

fmt : string or dict, optional

A format string for the label. Default is '%1.3f'

Alternatively, this can be a dictionary matching contour levels with arbitrary strings to use for each contour level (i.e., fmt[level]=string), or it can be any callable, such as a Formatter instance, that returns a string when called with a numeric contour level.

manual : bool or iterable, optional

If True, contour labels will be placed manually using mouse clicks. Click the first button near a contour to add a label, click the second button (or potentially both mouse buttons at once) to finish adding labels. The third button can be used to remove the last label added, but only if labels are not inline. Alternatively, the keyboard can be used to select label locations (enter to end label placement, delete or backspace act like the third mouse button, and any other key will select a label location).

manual can also be an iterable object of x,y tuples. Contour labels will be created as if mouse is clicked at each x,y positions.

rightside_up : bool, optional

If True, label rotations will always be plus or minus 90 degrees from level. Default is True.

use_clabeltext : bool, optional

If True, ClabelText class (instead of Text) is used to create labels. ClabelText recalculates rotation angles of texts during the drawing time, therefore this can be used if aspect of the axes changes. Default is False.


A list of Text instances for the labels.

Examples using matplotlib.axes.Axes.clabel