Section Navigation

matplotlib.pyplot.bar#

matplotlib.pyplot.bar(x, height, width=0.8, bottom=None, *, align='center', data=None, **kwargs)[source]#

Make a bar plot.

The bars are positioned at x with the given alignment. Their dimensions are given by height and width. The vertical baseline is bottom (default 0).

Many parameters can take either a single value applying to all bars or a sequence of values, one for each bar.

Parameters:

xfloat or array-like

The x coordinates of the bars. See also align for the alignment of the bars to the coordinates.

Bars are often used for categorical data, i.e. string labels below the bars. You can provide a list of strings directly to x. bar(['A', 'B', 'C'], [1, 2, 3]) is often a shorter and more convenient notation compared to bar(range(3), [1, 2, 3], tick_label=['A', 'B', 'C']). They are equivalent as long as the names are unique. The explicit tick_label notation draws the names in the sequence given. However, when having duplicate values in categorical x data, these values map to the same numerical x coordinate, and hence the corresponding bars are drawn on top of each other.

heightfloat or array-like

The height(s) of the bars.

Note that if bottom has units (e.g. datetime), height should be in units that are a difference from the value of bottom (e.g. timedelta).

widthfloat or array-like, default: 0.8

The width(s) of the bars.

Note that if x has units (e.g. datetime), then width should be in units that are a difference (e.g. timedelta) around the x values.

bottomfloat or array-like, default: 0

The y coordinate(s) of the bottom side(s) of the bars.

Note that if bottom has units, then the y-axis will get a Locator and Formatter appropriate for the units (e.g. dates, or categorical).

align{'center', 'edge'}, default: 'center'

Alignment of the bars to the x coordinates:

'center': Center the base on the x positions.
'edge': Align the left edges of the bars with the x positions.

To align the bars on the right edge pass a negative width and align='edge'.

Returns:

BarContainer: Container with all the bars and optionally errorbars.

Other Parameters:

colorcolor or list of color, optional

The colors of the bar faces. This is an alias for facecolor. If both are given, facecolor takes precedence.

facecolorcolor or list of color, optional

The colors of the bar faces. If both color and facecolor are given, *facecolor takes precedence.

edgecolorcolor or list of color, optional

The colors of the bar edges.

linewidthfloat or array-like, optional

Width of the bar edge(s). If 0, don't draw edges.

tick_labelstr or list of str, optional

The tick labels of the bars. Default: None (Use default numeric labels.)

labelstr or list of str, optional

A single label is attached to the resulting BarContainer as a legend label for the whole dataset. If a list is provided, it must be the same length as x and labels the individual bars. Repeated labels are not de-duplicated and will cause repeated label entries, so this is best used when bars also differ in style (e.g., by passing a list to color).

Tip: Use bar_label to place labels on the bars.

xerr, yerrfloat or array-like of shape(N,) or shape(2, N), optional

If not None, add horizontal / vertical errorbars to the bar tips. The values are +/- sizes relative to the data:

scalar: symmetric +/- values for all bars
shape(N,): symmetric +/- values for each bar
shape(2, N): Separate - and + values for each bar. First row contains the lower errors, the second row contains the upper errors.
None: No errorbar. (Default)

This is a convenience shortcut for an extra errorbar call. See its documentation and Different ways of specifying error bars for an example on the usage of xerr and yerr.

ecolorcolor or list of color, default: 'black'

The line color of the errorbars. Multiple colors are only supported if the errorbars do not have caps. If you need individually colored errorbars with caps, instead use explicit errorbar calls for each data point.

capsizefloat, default: rcParams["errorbar.capsize"] (default: 0.0)

The length of the error bar caps in points.

error_kwdict, optional

Dictionary of keyword arguments to be passed to the errorbar method. Values of ecolor or capsize defined here take precedence over the independent keyword arguments.

logbool, default: False

If True, set the y-axis to be log scale.

dataindexable object, optional

If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.

**kwargsRectangle properties

Property	Description
`agg_filter`	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
`alpha`	float or None
`angle`	unknown
`animated`	bool
`antialiased` or `aa`	bool or None
`bounds`	(left, bottom, width, height)
`capstyle`	`CapStyle` or {'butt', 'projecting', 'round'}
`clip_box`	`BboxBase` or None
`clip_on`	bool
`clip_path`	Patch or (Path, Transform) or None
`color`	color
`edgecolor` or `ec`	color or None
`edgegapcolor`	color or None
`facecolor` or `fc`	color or None
`figure`	`Figure` or `SubFigure`
`fill`	bool
`gid`	str
`hatch`	{'/', '\', '\|', '-', '+', 'x', 'o', 'O', '.', '*'}
`hatch_linewidth`	unknown
`hatchcolor`	color or 'edge' or None
`height`	unknown
`in_layout`	bool
`joinstyle`	`JoinStyle` or {'miter', 'round', 'bevel'}
`label`	object
`linestyle` or `ls`	{'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)
`linewidth` or `lw`	float or None
`mouseover`	bool
`path_effects`	list of `AbstractPathEffect`
`picker`	None or bool or float or callable
`rasterized`	bool
`sketch_params`	(scale: float, length: float, randomness: float)
`snap`	bool or None
`transform`	`Transform`
`url`	str
`visible`	bool
`width`	unknown
`x`	unknown
`xy`	(float, float)
`y`	unknown
`zorder`	float