You are reading documentation for the unreleased version of Matplotlib. Try searching for the released version of this page instead?
Applications are open for the 2018 John Hunter Matplotlib Summer Fellowship. Apply now!
Version 2.2.2.post1752+g4b1f956cb
Fork me on GitHub

Table Of Contents


matplotlib.pyplot.axes(arg=None, **kwargs)[source]

Add an axes to the current figure and make it the current axes.

Call signatures:

plt.axes(rect, projection=None, polar=False, **kwargs)
arg : { None, 4-tuple, Axes }

The exact behavior of this function depends on the type:

  • None: A new full window axes is added using subplot(111, **kwargs)

  • 4-tuple of floats rect = [left, bottom, width, height]. A new axes is added with dimensions rect in normalized (0, 1) units using add_axes on the current figure.

  • Axes: This is equivalent to It sets the current axes to arg. Note: This implicitly changes the current figure to the parent of arg.


    The use of an axes.Axes as an argument is deprecated and will be removed in v3.0. Please use instead.

projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, optional

The projection type of the Axes. str is the name of a costum projection, see projections. The default None results in a 'rectilinear' projection.

polar : boolean, optional

If True, equivalent to projection='polar'.

sharex, sharey : Axes, optional

Share the x or y axis with sharex and/or sharey. The axis will have the same limits, ticks, and scale as the axis of the shared axes.

label : str

A label for the returned axes.

axes : Axes (or a subclass of Axes)

The returned axes class depends on the projection used. It is Axes if rectilinear projection are used and projections.polar.PolarAxes if polar projection are used.

Other Parameters:

This method also takes the keyword arguments for the returned axes class. The keyword arguments for the rectilinear axes class Axes can be found in the following table but there might also be other keyword arguments if another projection is used, see the actual axes class.

Property Description
adjustable {'box', 'datalim'}
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
anchor 2-tuple of floats or {'C', 'SW', 'S', 'SE', ...}
animated bool
aspect {'auto', 'equal'} or num
autoscale_on bool
autoscalex_on bool
autoscaley_on bool
axes_locator Callable[[Axes, Renderer], Bbox]
axisbelow bool or 'line'
clip_box Bbox
clip_on bool
clip_path [(Path, Transform) | Patch | None]
contains callable
facecolor color
fc color
figure Figure
frame_on bool
gid str
in_layout bool
label object
navigate bool
navigate_mode unknown
path_effects AbstractPathEffect
picker None or bool or float or callable
position [left, bottom, width, height] or Bbox
rasterization_zorder float or None
rasterized bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
title str
transform Transform
url str
visible bool
xbound (lower: float, upper: float)
xlabel str
xlim (left: float, right: float)
xmargin float greater than -0.5
xscale {"linear", "log", "symlog", "logit", ...}
xticklabels List[str]
xticks list
ybound (lower: float, upper: float)
ylabel str
ylim (bottom: float, top: float)
ymargin float greater than -0.5
yscale {"linear", "log", "symlog", "logit", ...}
yticklabels List[str]
yticks list
zorder float


If the figure already has a axes with key (args, kwargs) then it will simply make that axes current and return it. This behavior is deprecated. Meanwhile, if you do not want this behavior (i.e., you want to force the creation of a new axes), you must use a unique set of args and kwargs. The axes label attribute has been exposed for this purpose: if you want two axes that are otherwise identical to be added to the figure, make sure you give them unique labels.


#Creating a new full window axes

#Creating a new axes with specified dimensions and some kwargs
plt.axes((left, bottom, width, height), facecolor='w')