matplotlib.pyplot.axes

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

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

Call signatures:

plt.axes()
plt.axes(rect, projection=None, polar=False, **kwargs)
plt.axes(ax)
Parameters
argNone or 4-tuple

The exact behavior of this function depends on the type:

  • None: A new full window axes is added using subplot(**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.

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

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

polarbool, default: False

If True, equivalent to projection='polar'.

sharex, shareyAxes, 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.

labelstr

A label for the returned axes.

Returns
Axes, or a subclass of Axes

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

Other Parameters
**kwargs

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

scalar or None

anchor

(float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}

animated

bool

aspect

{'auto', 'equal'} or float

autoscale_on

bool

autoscalex_on

bool

autoscaley_on

bool

axes_locator

Callable[[Axes, Renderer], Bbox]

axisbelow

bool or 'line'

box_aspect

float or None

clip_box

Bbox

clip_on

bool

clip_path

Patch or (Path, Transform) or None

facecolor or 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

prop_cycle

unknown

rasterization_zorder

float or None

rasterized

bool

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

title

str

transform

Transform

url

str

visible

bool

xbound

unknown

xlabel

str

xlim

(bottom: float, top: float)

xmargin

float greater than -0.5

xscale

{"linear", "log", "symlog", "logit", ...} or ScaleBase

xticklabels

unknown

xticks

unknown

ybound

unknown

ylabel

str

ylim

(bottom: float, top: float)

ymargin

float greater than -0.5

yscale

{"linear", "log", "symlog", "logit", ...} or ScaleBase

yticklabels

unknown

yticks

unknown

zorder

float

Notes

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.

Examples

# Creating a new full window axes
plt.axes()

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