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


Table Of Contents

This Page


matplotlib.pyplot.subplot(*args, **kwargs)

Return a subplot axes positioned by the given grid definition.

Typical call signature:

subplot(nrows, ncols, plot_number)

Where nrows and ncols are used to notionally split the figure into nrows * ncols sub-axes, and plot_number is used to identify the particular subplot that this function is to create within the notional grid. plot_number starts at 1, increments across rows first and has a maximum of nrows * ncols.

In the case when nrows, ncols and plot_number are all less than 10, a convenience exists, such that the a 3 digit number can be given instead, where the hundreds represent nrows, the tens represent ncols and the units represent plot_number. For instance:


produces a subaxes in a figure which represents the top plot (i.e. the first) in a 2 row by 1 column notional grid (no grid actually exists, but conceptually this is how the returned subplot has been positioned).


Creating a subplot will delete any pre-existing subplot that overlaps with it beyond sharing a boundary:

import matplotlib.pyplot as plt
# plot a line, implicitly creating a subplot(111)
# now create a subplot which represents the top plot of a grid
# with 2 rows and 1 column. Since this subplot will overlap the
# first, the plot (and its axes) previously created, will be removed
plt.subplot(212, facecolor='y') # creates 2nd subplot with yellow background

If you do not want this behavior, use the add_subplot() method or the axes() function instead.

Keyword arguments:

The background color of the subplot, which can be any valid color specifier. See matplotlib.colors for more information.
A boolean flag indicating whether the subplot plot should be a polar projection. Defaults to False.
A string giving the name of a custom projection to be used for the subplot. This projection must have been previously registered. See matplotlib.projections.

See also

For additional information on axes() and subplot() keyword arguments.
For an example


(Source code, png, pdf)