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

See also

Figure.add_axes

pyplot.subplot

Figure.add_subplot

Figure.subplots

pyplot.subplots

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')

Examples using matplotlib.pyplot.axes