Text of matplotlib.org › stable › api › legend_api.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

matplotlib.legend — Matplotlib 3.11.2 documentation

Skip to main content Plot types User guide Tutorials Examples Reference Contribute Releases Gitter Discourse GitHub matplotlib.legend # The legend module defines the Legend class, which is responsible for drawing legends associated with Axes and/or figures. Important It is unlikely that you would ever create a Legend instance manually. Most users would normally create a legend via the legend function. For more details on legends there is also a legend guide .

The Legend class is a container of legend handles and legend texts. The legend handler map specifies how to create legend handles from artists (lines, patches, etc.) in the Axes or figures. Default legend handlers are defined in the legend_handler module. While not all artist types are covered by the default legend handlers, custom legend handlers can be defined to support arbitrary objects. See the :ref`<legend_guide>` for more information. class matplotlib.legend.

DraggableLegend ( legend , use_blit = False , update = 'loc' ) [source] # Bases: DraggableOffsetBox Wrapper around a Legend to support mouse dragging. Parameters : legend Legend The Legend instance to wrap. use_blit bool, optional Use blitting for faster image composition. For details see FuncAnimation . update {'loc', 'bbox'}, optional If "loc", update the loc parameter of the legend upon finalizing. If "bbox", update the bbox_to_anchor parameter. finalize_offset ( ) [source] # class matplotlib.legend.

Legend ( parent , handles , labels , * , loc = None , numpoints = None , markerscale = None , markerfirst = True , reverse = False , scatterpoints = None , scatteryoffsets = None , prop = None , fontsize = None , labelcolor = None , borderpad = None , labelspacing = None , handlelength = None , handleheight = None , handletextpad = None , borderaxespad = None , columnspacing = None , ncols = 1 , mode = None , fancybox = None , shadow = None , title = None , title_fontsize = None , framealpha = None , edgecolor = None , facecolor = None , linewidth = None , bbox_to_anchor = None , bbox_transform = None , frameon = None , handler_map = None , title_fontproperties = None , alignment = 'center' , ncol = 1 , draggable = False ) [source] # Bases: Artist Place a legend on the figure/axes.

Parameters : parent Axes or Figure The artist that contains the legend. handles list of ( Artist or tuple of Artist ) A list of Artists (lines, patches) to be added to the legend. labels list of str A list of labels to show next to the artists. The length of handles and labels should be the same. If they are not, they are truncated to the length of the shorter list. Attributes : legend_handles List of Artist objects added as legend entries.

Added in version 3.7. Other Parameters : loc str or pair of floats, default: rcParams["legend.loc"] (default: 'best' ) for Axes, 'upper right' for Figure The location of the legend. The string locations place the legend at the corresponding position within the bounding box, which by default is the full axes/figure area. The bounding box can be changed via bbox_to_anchor . The positions are visualized below: +--------------+--------------+---------------+ | 'upper left' | 'upper center' | 'upper right' | +--------------+--------------+---------------+ | 'center left' | 'center' | 'center right' | +--------------+--------------+---------------+ | 'lower left' | 'lower center' | 'lower right' | +--------------+--------------+---------------+ The string 'best' places the legend at the location, among the nine locations defined so far, with the minimum overlap with other drawn artists.

This currently takes into account most, but not all, artists added to the Axes via plotting functions. In particular it does not consider inset axes, titles, or axis labels. The computation of the best position can be expensive for plots with large amounts of data. If speed becomes a concern, you may may benefit from providing a specific location. The location can also be a 2-tuple giving the coordinates of the lower-left corner of the legend in axes/figure coordinates (in which case bbox_to_anchor will be ignored).

For back-compatibility, 'center right' (but no other location) can also be spelled 'right' , and each "string" location can also be given as a numeric value: Location String Location Code 'best' (Axes only) 0 'upper right' 1 'upper left' 2 'lower left' 3 'lower right' 4 'right' 5 'center left' 6 'center right' 7 'lower center' 8 'upper center' 9 'center' 10 If a figure is using the constrained layout manager, the string codes of the loc keyword argument can get better layout behaviour using the prefix 'outside'.

There is ambiguity at the corners, so 'outside upper right' will make space for the legend above the rest of the axes in the layout, and 'outside right upper' will make space on the right side of the layout. In addition to the values of loc listed above, we have 'outside right upper', 'outside right lower', 'outside left upper', and 'outside left lower'. See Legend guide for more details. bbox_to_anchor BboxBase , 2-tuple, or 4-tuple of floats Box that is used to position the legend in conjunction with loc .

This is an advanced option for free placement of the legend. For most use cases, loc alone is sufficient. Defaults to axes.bbox (if called as a method to Axes.legend ) or figure.bbox (if figure.legend ). Bbox coordinates are interpreted in the coordinate system given by bbox_transform , with the default transform Axes or Figure coordinates, depending on which legend is called. If a 4-tuple or BboxBase is given, then it specifies the bbox (x, y, width, height) that the legend is placed in.

To put the legend in the best location in the bottom right quadrant of the Axes (or figure): loc = 'best' , bbox_to_anchor = ( 0.5 , 0. , 0.5 , 0.5 ) A 2-tuple (x, y) places the corner of the legend specified by loc at x, y. For example, to put the legend's upper right-hand corner in the center of the Axes (or figure) the following keywords can be used: loc = 'upper right' , bbox_to_anchor = ( 0.5 , 0.5 ) For more details on legend positioning, see the Legend guide . ncols int, default: 1 The number of columns that the legend has.

For backward compatibility, the spelling ncol is also supported but it is discouraged. If both are given, ncols takes precedence. prop None or FontProperties or dict The font properties of the legend. If None (default), the current matplotlib.rcParams will be used. fontsize int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} The font size of the legend. If the value is numeric the size will be the absolute font size in points.

String values are relative to the current default font size. This argument is only used if prop is not specified. labelcolor str or list, default: rcParams["legend.labelcolor"] (default: 'None' ) The color of the text in the legend. Either a valid color string (for example, 'red'), or a list of color strings. The labelcolor can also be made to match the color of the line or marker using 'linecolor', 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec').

Labelcolor can be set globally using rcParams["legend.labelcolor"] (default: 'None' ). If None, use rcParams["text.color"] (default: 'black' ). numpoints int, default: rcParams["legend.numpoints"] (default: 1 ) The number of marker points in the legend when creating a legend entry for a Line2D (line). scatterpoints int, default: rcParams["legend.scatterpoints"] (default: 1 ) The number of marker points in the legend when creating a legend entry for a PathCollection (scatter plot). scatteryoffsets iterable of floats, default: [0.375, 0.5, 0.3125] The vertical offset (relative to the font size) for the markers created for a scatter plot legend entry.

0.0 is at the base the legend text, and 1.0 is at the top. To draw all markers at the same height, set to [0.5] . markerscale float, default: rcParams["legend.markerscale"] (default: 1.0 ) The relative size of legend markers compared to the originally dra

The rest of this page is on the live site.