You are reading an old version of the documentation (v2.2.0). For the latest version see
Version 2.2.0
Fork me on GitHub

This Page


Axes.pcolormesh(*args, data=None, **kwargs)

Plot a quadrilateral mesh.

Call signatures:

pcolormesh(X, Y, C)
pcolormesh(C, **kwargs)

Create a pseudocolor plot of a 2-D array.

pcolormesh is similar to pcolor(), but uses a different mechanism and returns a different object; pcolor returns a PolyCollection but pcolormesh returns a QuadMesh. It is much faster, so it is almost always preferred for large arrays.

C may be a masked array, but X and Y may not. Masked array support is implemented via cmap and norm; in contrast, pcolor() simply does not draw quadrilaterals with masked colors or vertices.



Other Parameters:

cmap : Colormap, optional

A matplotlib.colors.Colormap instance. If None, use rc settings.

norm : Normalize, optional

A matplotlib.colors.Normalize instance is used to scale luminance data to 0,1. If None, defaults to normalize().

vmin, vmax : scalar, optional

vmin and vmax are used in conjunction with norm to normalize luminance data. If either is None, it is autoscaled to the respective min or max of the color array C. If not None, vmin or vmax passed in here override any pre-existing values supplied in the norm instance.

shading : [ ‘flat’ | ‘gouraud’ ], optional

‘flat’ indicates a solid color for each quad. When ‘gouraud’, each quad will be Gouraud shaded. When gouraud shading, edgecolors is ignored.

edgecolors : string, color, color sequence, optional

  • If None, the rc setting is used by default.
  • If 'None', edges will not be visible.
  • If 'face', edges will have the same color as the faces.

An mpl color or sequence of colors will also set the edge color.

alpha : scalar, optional

Alpha blending value. Must be between 0 and 1.

See also

For an explanation of the grid orientation (Grid Orientation) and the expansion of 1-D X and/or Y to 2-D arrays.


kwargs can be used to control the matplotlib.collections.QuadMesh 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
alpha float or None
animated bool
antialiased or antialiaseds Boolean or sequence of booleans
array ndarray
capstyle unknown
clim a length 2 sequence of floats; may be overridden in methods that have vmin and vmax kwargs.
clip_box a Bbox instance
clip_on bool
clip_path [(Path, Transform) | Patch | None]
cmap a colormap or registered colormap name
color matplotlib color arg or sequence of rgba tuples
contains a callable function
edgecolor or edgecolors matplotlib color spec or sequence of specs
facecolor or facecolors matplotlib color spec or sequence of specs
figure a Figure instance
gid an id string
hatch [ ‘/’ | ‘' | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ]
joinstyle unknown
label object
linestyle or dashes or linestyles [‘solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (offset, on-off-dash-seq) | '-' | '--' | '-.' | ':' | 'None' | ' ' | '']
linewidth or linewidths or lw float or sequence of floats
norm Normalize
offset_position [ ‘screen’ | ‘data’ ]
offsets float or sequence of floats
path_effects AbstractPathEffect
picker [None | bool | float | callable]
pickradius float distance in points
rasterized bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
transform Transform
url a url string
urls List[str] or None
visible bool
zorder float


In addition to the above described arguments, this function can take a data keyword argument. If such a data argument is given, the following arguments are replaced by data[<arg>]:

  • All positional and all keyword arguments.