19/04/2024 Introduction to Axes (or Subplots) — Matplotlib 3.8.

4 documentation

  

 › Using Matplotlib › Axes and subplots › Introduction to Axes (or Subplots)

Introduction to Axes (or Subplots)

Matplotlib Axes are the gateway to creating your data visualizations. Once an Axes is placed on a figure there are many methods
that can be used to add data to the Axes. An Axes typically has a pair of Axis Artists that define the data coordinate system, and
include methods to add annotations like x- and y-labels, titles, and legends.

Anatomy of a Figure

In the picture above, the Axes object was created with ax = fig.subplots() . Everything else on the figure was created with
methods on this ax object, or can be accessed from it. If we want to change the label on the x-axis, we call ax.set_xlabel('New
Label') , if we want to plot some data we call ax.plot(x, y) . Indeed, in the figure above, the only Artist that is not part of the
Axes is the Figure itself, so the axes.Axes class is really the gateway to much of Matplotlib's functionality.

Note that Axes are so fundamental to the operation of Matplotlib that a lot of material here is duplicate of that in Quick start
guide.

Creating Axes
Skip to main content
import matplotlib.pyplot as plt
https://matplotlib.org/stable/users/explain/axes/axes_intro.html 1/6
19/04/2024 Introduction to Axes (or Subplots) — Matplotlib 3.8.4 documentation
import matplotlib.pyplot as plt
import numpy as np

fig, axs = plt.subplots(ncols=2, nrows=2, figsize=(3.5, 2.5),

layout="constrained")
# for each Axes, add an artist, in this case a nice label in the middle...
for row in range(2):
for col in range(2):
axs[row, col].annotate(f'axs[{row}, {col}]', (0.5, 0.5),
transform=axs[row, col].transAxes,
ha='center', va='center', fontsize=18,
color='darkgrey')
fig.suptitle('plt.subplots()')

(  Source code ,  2x.png ,  png )

Axes are added using methods on Figure objects, or via the pyplot interface. These methods are discussed in more detail in
Creating Figures and Arranging multiple Axes in a Figure. However, for instance add_axes will manually position an Axes on the
page. In the example above subplots put a grid of subplots on the figure, and axs is a (2, 2) array of Axes, each of which can
have data added to them.

There are a number of other methods for adding Axes to a Figure:

Figure.add_axes : manually position an Axes. fig.add_axes([0, 0, 1, 1]) makes an Axes that fills the whole figure.

pyplot.subplots and Figure.subplots : add a grid of Axes as in the example above. The pyplot version returns both the
Figure object and an array of Axes. Note that fig, ax = plt.subplots() adds a single Axes to a Figure.
pyplot.subplot_mosaic and Figure.subplot_mosaic : add a grid of named Axes and return a dictionary of axes. For fig,
axs = plt.subplot_mosaic([['left', 'right'], ['bottom', 'bottom']]) , axs['left'] is an Axes in the top row on the
left, and axs['bottom'] is an Axes that spans both columns on the bottom.

See Arranging multiple Axes in a Figure for more detail on how to arrange grids of Axes on a Figure.

Axes plotting methods

Most of the high-level plotting methods are accessed from the axes.Axes class. See the API documentation for a full curated list,
and Plot types for examples. A basic example is axes.Axes.plot :

fig, ax = plt.subplots(figsize=(4, 3))

np.random.seed(19680801)
t = np.arange(100)
x = np.cumsum(np.random.randn(100))
lines = ax.plot(t, x)

(  Source code ,  2x.png ,  png ) Skip to main content

https://matplotlib.org/stable/users/explain/axes/axes_intro.html 2/6
19/04/2024 Introduction to Axes (or Subplots) — Matplotlib 3.8.4 documentation

Note that plot returns a list of lines Artists which can subsequently be manipulated, as discussed in Introduction to Artists.

A very incomplete list of plotting methods is below. Again, see Plot types for more examples, and axes.Axes for the full list of
methods.

Pairwise data plot , scatter , bar , step ,

Array objects pcolormesh , contour , quiver , streamplot , imshow

Statistical distributions hist , errorbar , hist2d , pie , boxplot , violinplot

Irregularly gridded data tricontour , tripcolor

Axes labelling and annotation

Usually we want to label the Axes with an xlabel, ylabel, and title, and often we want to have a legend to differentiate plot
elements. The Axes class has a number of methods to create these annotations.

fig, ax = plt.subplots(figsize=(5, 3), layout='constrained')

np.random.seed(19680801)
t = np.arange(200)
x = np.cumsum(np.random.randn(200))
y = np.cumsum(np.random.randn(200))
linesx = ax.plot(t, x, label='Random walk x')
linesy = ax.plot(t, y, label='Random walk y')

ax.set_xlabel('Time [s]')
ax.set_ylabel('Distance [km]')
ax.set_title('Random walk example')
ax.legend()

(  Source code ,  2x.png ,  png )

Skip to main content

https://matplotlib.org/stable/users/explain/axes/axes_intro.html 3/6
19/04/2024 Introduction to Axes (or Subplots) — Matplotlib 3.8.4 documentation

These methods are relatively straight-forward, though there are a number of Text properties and layout that can be set on the
text objects, like fontsize, fontname, horizontalalignment. Legends can be much more complicated; see Legend guide for more
details.

Note that text can also be added to axes using text , and annotate . This can be quite sophisticated: see Text properties and
layout and Annotations for more information.

Axes limits, scales, and ticking

Each Axes has two (or more) Axis objects, that can be accessed via xaxis and yaxis properties. These have substantial
number of methods on them, and for highly customizable Axis-es it is useful to read the API at Axis . However, the Axes class
offers a number of helpers for the most common of these methods. Indeed, the set_xlabel , discussed above, is a helper for the
set_label_text .

Other important methods set the extent on the axes ( set_xlim , set_ylim ), or more fundamentally the scale of the axes. So for
instance, we can make an Axis have a logarithmic scale, and zoom in on a sub-portion of the data:

fig, ax = plt.subplots(figsize=(4, 2.5), layout='constrained')

np.random.seed(19680801)
t = np.arange(200)
x = 2**np.cumsum(np.random.randn(200))
linesx = ax.plot(t, x)
ax.set_yscale('log')
ax.set_xlim([20, 180])

(  Source code ,  2x.png ,  png )

Skip to main content

https://matplotlib.org/stable/users/explain/axes/axes_intro.html 4/6
19/04/2024 Introduction to Axes (or Subplots) — Matplotlib 3.8.4 documentation

The Axes class also has helpers to deal with Axis ticks and their labels. Most straight-forward is set_xticks and set_yticks
which manually set the tick locations and optionally their labels. Minor ticks can be toggled with minorticks_on or
minorticks_off .

Many aspects of Axes ticks and tick labeling can be adjusted using tick_params . For instance, to label the top of the axes instead
of the bottom,color the ticks red, and color the ticklabels green:

fig, ax = plt.subplots(figsize=(4, 2.5))

ax.plot(np.arange(10))
ax.tick_params(top=True, labeltop=True, color='red', axis='x',
labelcolor='green')

(  Source code ,  2x.png ,  png )

More fine-grained control on ticks, setting scales, and controlling the Axis can be highly customized beyond these Axes-level
helpers.

Axes layout
Sometimes it is important to set the aspect ratio of a plot in data space, which we can do with set_aspect :

fig, axs = plt.subplots(ncols=2, figsize=(7, 2.5), layout='constrained')

np.random.seed(19680801) Skip to main content
t = np.arange(200)
https://matplotlib.org/stable/users/explain/axes/axes_intro.html 5/6
19/04/2024 Introduction to Axes (or Subplots) — Matplotlib 3.8.4 documentation
p g ( )
x = np.cumsum(np.random.randn(200))
axs[0].plot(t, x)
axs[0].set_title('aspect="auto"')

axs[1].plot(t, x)
axs[1].set_aspect(3)
axs[1].set_title('aspect=3')

(  Source code ,  2x.png ,  png )

© Copyright 2002–2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the Matplotlib
development team; 2012–2024 The Matplotlib development team. Built with the PyData
Created using Sphinx 7.2.6. Sphinx Theme 0.13.3.

Built from v3.8.4-2-g4dcfcf8b7b.

https://matplotlib.org/stable/users/explain/axes/axes_intro.html 6/6