### Navigation

- index
- modules |
- next |
- previous |
- home|
- examples|
- tutorials|
- pyplot|
- docs »
- The Matplotlib API »

# `Axes` class

class `matplotlib.axes.``Axes`(fig, rect, facecolor=None, frameon=True, sharex=None, sharey=None, label=”, xscale=None, yscale=None, axisbg=None, **kwargs)

  The `Axes` contains most of the figure elements: `Axis`, `Tick`, `Line2D`, `Text`, `Polygon`, etc., and sets the coordinate system.

  The `Axes` instance supports callbacks through a callbacks attribute which is a `CallbackRegistry` instance. The events you can connect to are ‘xlim_changed’ and ‘ylim_changed’ and the callback will be called with func(ax) where ax is the `Axes` instance.

Table of Contents

- Plotting
  - Basic
  - Spans
  - Spectral
  - Statistics
  - Binned
  - Contours
  - Array
  - Unstructured Triangles
  - Text and Annotations
  - Fields
- Clearing
- Appearance
- Property cycle
- Axis / limits
  - Axis Limits and direction
  - Axis Labels, title, and legend
  - Axis scales
  - Autoscaling and margins
  - Aspect ratio
  - Ticks and tick labels
- Units
- Adding Artists
- Twinning
- Axes Position
- Async/Event based
- Interactive
- Children
- Drawing
- Bulk property manipulation
- General Artist Properties
- Artist Methods
- Projection
- Other
- Inheritance

## Plotting

### Basic

`Axes.plot` | Plot lines and/or markers to the `Axes`.
`Axes.errorbar` | Plot an errorbar graph.
`Axes.scatter` | Make a scatter plot of `x` vs `y`.
`Axes.plot_date` | A plot with data that contains dates.
`Axes.step` | Make a step plot.
`Axes.loglog` | Make a plot with log scaling on both the x and y axis.
`Axes.semilogx` | Make a plot with log scaling on the x axis.
`Axes.semilogy` | Make a plot with log scaling on the `y` axis.
`Axes.fill_between` | Make filled polygons between two curves.
`Axes.fill_betweenx` | Make filled polygons between two horizontal curves.
`Axes.bar` | Make a bar plot.
`Axes.barh` | Make a horizontal bar plot.
`Axes.stem` | Create a stem plot.
`Axes.eventplot` | Plot identical parallel lines at the given positions.
`Axes.pie` | Plot a pie chart.
`Axes.stackplot` | Draws a stacked area plot.
`Axes.broken_barh` | Plot horizontal bars.
`Axes.vlines` | Plot vertical lines.
`Axes.hlines` | Plot horizontal lines at each `y` from `xmin` to `xmax`.
`Axes.fill` | Plot filled polygons.

### Spans

`Axes.axhline` | Add a horizontal line across the axis.
`Axes.axhspan` | Add a horizontal span (rectangle) across the axis.
`Axes.axvline` | Add a vertical line across the axes.
`Axes.axvspan` | Add a vertical span (rectangle) across the axes.

### Spectral

`Axes.acorr` | Plot the autocorrelation of `x`.
`Axes.angle_spectrum` | Plot the angle spectrum.
`Axes.cohere` | Plot the coherence between x and y.
`Axes.csd` | Plot the cross-spectral density.
`Axes.magnitude_spectrum` | Plot the magnitude spectrum.
`Axes.phase_spectrum` | Plot the phase spectrum.
`Axes.psd` | Plot the power spectral density.
`Axes.specgram` | Plot a spectrogram.
`Axes.xcorr` | Plot the cross correlation between x and y.

### Statistics

`Axes.boxplot` | Make a box and whisker plot.
`Axes.violinplot` | Make a violin plot.
`Axes.violin` | Drawing function for violin plots.
`Axes.bxp` | Drawing function for box and whisker plots.

### Binned

`Axes.hexbin` | Make a hexagonal binning plot.
`Axes.hist` | Plot a histogram.
`Axes.hist2d` | Make a 2D histogram plot.

### Contours

`Axes.clabel` | Label a contour plot.
`Axes.contour` | Plot contours.
`Axes.contourf` | Plot contours.

### Array

`Axes.imshow` | Display an image on the axes.
`Axes.matshow` | Plot a matrix or array as an image.
`Axes.pcolor` | Create a pseudocolor plot of a 2-D array.
`Axes.pcolorfast` | pseudocolor plot of a 2-D array
`Axes.pcolormesh` | Plot a quadrilateral mesh.
`Axes.spy` | Plot the sparsity pattern on a 2-D array.

### Unstructured Triangles

`Axes.tripcolor` | Create a pseudocolor plot of an unstructured triangular grid.
`Axes.triplot` | Draw a unstructured triangular grid as lines and/or markers.
`Axes.tricontour` | Draw contours on an unstructured triangular grid.
`Axes.tricontourf` | Draw contours on an unstructured triangular grid.

### Text and Annotations

`Axes.annotate` | Annotate the point `xy` with text `s`.
`Axes.text` | Add text to the axes.
`Axes.table` | Add a table to the current axes.
`Axes.arrow` | Add an arrow to the axes.

### Fields

`Axes.barbs` | Plot a 2-D field of barbs.
`Axes.quiver` | Plot a 2-D field of arrows.
`Axes.quiverkey` | Add a key to a quiver plot.
`Axes.streamplot` | Draws streamlines of a vector flow.

## Clearing

`Axes.cla` | Clear the current axes.
`Axes.clear` | clear the axes

## Appearance

`Axes.axis` | Set axis properties.
`Axes.set_axis_off` | turn off the axis
`Axes.set_axis_on` | turn on the axis
`Axes.set_frame_on` | Set whether the axes rectangle patch is drawn
`Axes.get_frame_on` | Get whether the axes rectangle patch is drawn
`Axes.set_axisbelow` | Set whether the axis ticks and gridlines are above or below most
`Axes.get_axisbelow` | Get whether axis below is true or not
`Axes.grid` | Turn the axes grids on or off.
`Axes.get_axis_bgcolor` | Deprecated since version 2.0.
`Axes.get_facecolor` |
`Axes.get_fc` |
`Axes.set_facecolor` |
`Axes.set_fc` |
`Axes.set_axis_bgcolor` | Deprecated since version 2.0.

## Property cycle

`Axes.set_prop_cycle` | Set the property cycle for any future plot commands on this Axes.
`Axes.set_color_cycle` | Set the color cycle for any future plot commands on this Axes.

## Axis / limits

`Axes.get_yaxis` | Return the YAxis instance
`Axes.get_xaxis` | Return the XAxis instance

### Axis Limits and direction

`Axes.invert_xaxis` | Invert the x-axis.
`Axes.invert_yaxis` | Invert the y-axis.
`Axes.xaxis_inverted` | Returns True if the x-axis is inverted.
`Axes.yaxis_inverted` | Returns True if the y-axis is inverted.
`Axes.set_xlim` | Set the data limits for the x-axis
`Axes.set_ylim` | Set the data limits for the y-axis
`Axes.get_ylim` | Get the y-axis range
`Axes.get_xlim` | Get the x-axis range
`Axes.update_datalim` | Update the data lim bbox with seq of xy tups or equiv.
`Axes.update_datalim_bounds` | Update the datalim to include the given
`Axes.update_datalim_numerix` | Deprecated since version 2.0.
`Axes.set_ybound` | Set the lower and upper numerical bounds of the y-axis.
`Axes.set_xbound` | Set the lower and upper numerical bounds of the x-axis.
`Axes.get_ybound` | Return y-axis numerical bounds in the form of
`Axes.get_xbound` | Returns the x-axis numerical bounds

### Axis Labels, title, and legend

`Axes.get_xlabel` | Get the xlabel text string.
`Axes.get_ylabel` | Get the ylabel text string.
`Axes.set_xlabel` | Set the label for the xaxis.
`Axes.set_ylabel` | Set the label for the yaxis
`Axes.set_title` | Set a title for the axes.
`Axes.get_title` | Get an axes title.
`Axes.legend` | Places a legend on the axes.
`Axes.get_legend` | Return the legend.Legend instance, or None if no legend is defined
`Axes.get_legend_handles_labels` | Return handles and labels for legend

### Axis scales

`Axes.set_xscale` | Set the x-axis scale
`Axes.get_xscale` | Return the xaxis scale string: linear, log, logit, symlog
`Axes.get_yscale` | Return the yaxis scale string: linear, log, logit, symlog
`Axes.set_yscale` | Set the y-axis scale

### Autoscaling and margins

`Axes.use_sticky_edges` | When autoscaling, whether to obey all `Artist.sticky_edges`.
`Axes.margins` | Set or retrieve autoscaling margins.
`Axes.set_xmargin` | Set padding of X data limits prior to autoscaling.
`Axes.set_ymargin` | Set padding of Y data limits prior to autoscaling.
`Axes.relim` | Recompute the data limits based on current artists.
`Axes.autoscale` | Autoscale the axis view to the data (toggle).
`Axes.autoscale_view` | Autoscale the view limits using the data limits.
`Axes.get_autoscale_on` | Get whether autoscaling is applied for both axes on plot commands
`Axes.set_autoscale_on` | Set whether autoscaling is applied on plot commands
`Axes.get_autoscalex_on` | Get whether autoscaling for the x-axis is applied on plot commands
`Axes.set_autoscalex_on` | Set whether autoscaling for the x-axis is applied on plot commands
`Axes.get_autoscaley_on` | Get whether autoscaling for the y-axis is applied on plot commands
`Axes.set_autoscaley_on` | Set whether autoscaling for the y-axis is applied on plot commands

### Aspect ratio

`Axes.apply_aspect` | Use `_aspect()` and `_adjustable()` to modify the axes box or the view limits.
`Axes.get_aspect` |
`Axes.set_aspect` | aspect
`Axes.get_adjustable` |
`Axes.set_adjustable` | ACCEPTS: [ ‘box’ | ‘datalim’ | ‘box-forced’]

### Ticks and tick labels

`Axes.xaxis_date` | Sets up x-axis ticks and labels that treat the x data as dates.
`Axes.yaxis_date` | Sets up y-axis ticks and labels that treat the y data as dates.
`Axes.get_xmajorticklabels` | Get the xtick labels as a list of `Text` instances.
`Axes.get_xminorticklabels` | Get the x minor tick labels as a list of `matplotlib.text.Text` instances.
`Axes.get_xticklabels` | Get the x tick labels as a list of `Text` instances.
`Axes.get_xticklines` | Get the xtick lines as a list of Line2D instances
`Axes.get_xticks` | Return the x ticks as a list of locations
`Axes.get_ymajorticklabels` | Get the major y tick labels as a list of `Text` instances.
`Axes.get_yminorticklabels` | Get the minor y tick labels as a list of `Text` instances.
`Axes.get_yticklabels` | Get the x tick labels as a list of `Text` instances.
`Axes.get_yticklines` | Get the ytick lines as a list of Line2D instances
`Axes.get_yticks` | Return the y ticks as a list of locations
`Axes.minorticks_off` | Remove minor ticks from the axes.
`Axes.minorticks_on` | Add autoscaling minor ticks to the axes.
`Axes.set_xticklabels` | Set the xtick labels with list of string labels
`Axes.set_xticks` | Set the x ticks with list of ticks
`Axes.set_yticklabels` | Set the y-tick labels with list of strings labels
`Axes.set_yticks` | Set the y ticks with list of ticks
`Axes.get_xgridlines` | Get the x grid lines as a list of Line2D instances
`Axes.get_ygridlines` | Get the y grid lines as a list of Line2D instances
`Axes.ticklabel_format` | Change the `ScalarFormatter` used by default for linear axes.
`Axes.tick_params` | Change the appearance of ticks and tick labels.
`Axes.locator_params` | Control behavior of tick locators.

## Units

`Axes.convert_xunits` | For artists in an axes, if the xaxis has units support,
`Axes.convert_yunits` | For artists in an axes, if the yaxis has units support,
`Axes.have_units` | Return True if units are set on the x or y axes

## Adding Artists

`Axes.add_artist` | Add any `Artist` to the axes.
`Axes.add_collection` | Add a `Collection` instance to the axes.
`Axes.add_container` | Add a `Container` instance to the axes.
`Axes.add_image` | Add a `AxesImage` to the axes.
`Axes.add_line` | Add a `Line2D` to the list of plot
`Axes.add_patch` | Add a `Patch` p to the list of axes patches; the clipbox will be set to the Axes clipping box.
`Axes.add_table` | Add a `Table` instance to the

## Twinning

`Axes.twinx` | Create a twin Axes sharing the xaxis
`Axes.twiny` | Create a twin Axes sharing the yaxis
`Axes.get_shared_x_axes` | Return a copy of the shared axes Grouper object for x axes
`Axes.get_shared_y_axes` | Return a copy of the shared axes Grouper object for y axes

## Axes Position

`Axes.get_anchor` |
`Axes.set_anchor` | anchor
`Axes.get_axes_locator` | return axes_locator
`Axes.set_axes_locator` | set axes_locator
`Axes.reset_position` | Make the original position the active position
`Axes.get_position` | Return the a copy of the axes rectangle as a Bbox
`Axes.set_position` | Set the axes position

## Async/Event based

`Axes.stale` | If the artist is ‘stale’ and needs to be re-drawn for the output to match the internal state of the artist.
`Axes.pchanged` | Fire an event when property changed, calling all of the registered callbacks.
`Axes.add_callback` | Adds a callback function that will be called whenever one of the `Artist`’s properties changes.
`Axes.remove_callback` | Remove a callback based on its id.

## Interactive

`Axes.can_pan` | Return True if this axes supports any pan/zoom button functionality.
`Axes.can_zoom` | Return True if this axes supports the zoom box button functionality.
`Axes.get_navigate` | Get whether the axes responds to navigation commands
`Axes.set_navigate` | Set whether the axes responds to navigation toolbar commands
`Axes.get_navigate_mode` | Get the navigation toolbar button status: ‘PAN’, ‘ZOOM’, or None
`Axes.set_navigate_mode` | Set the navigation toolbar button status;
`Axes.start_pan` | Called when a pan operation has started.
`Axes.drag_pan` | Called when the mouse moves during a pan operation.
`Axes.end_pan` | Called when a pan operation completes (when the mouse button
`Axes.format_coord` | Return a format string formatting the x, y coord
`Axes.format_cursor_data` | Return cursor data string formatted.
`Axes.format_xdata` | Return x string formatted.
`Axes.format_ydata` | Return y string formatted.
`Axes.hitlist` | List the children of the artist which contain the mouse event event.
`Axes.mouseover` |
`Axes.in_axes` | Return True if the given mouseevent (in display coords)
`Axes.pick` | Trigger pick event
`Axes.pickable` | Return True if `Artist` is pickable.
`Axes.get_picker` | Return the picker object used by this artist
`Axes.set_picker` | Set the epsilon for picking used by this artist
`Axes.set_contains` | Replace the contains test used by this artist.
`Axes.get_contains` | Return the _contains test used by the artist, or None for default.
`Axes.contains` | Test whether the mouse event occurred in the axes.
`Axes.contains_point` | Returns True if the point (tuple of x,y) is inside the axes (the area defined by the its patch).
`Axes.get_cursor_data` | Get the cursor data for a given event.
`Axes.get_cursor_props` | Deprecated since version 2.1.
`Axes.set_cursor_props` | Deprecated since version 2.1.

## Children

`Axes.get_children` | return a list of child artists
`Axes.get_images` | return a list of Axes images contained by the Axes
`Axes.get_lines` | Return a list of lines contained by the Axes
`Axes.findobj` | Find artist objects.

## Drawing

`Axes.draw` | Draw everything (plot lines, axes, labels)
`Axes.draw_artist` | This method can only be used after an initial draw which caches the renderer.
`Axes.redraw_in_frame` | This method can only be used after an initial draw which caches the renderer.
`Axes.get_renderer_cache` |
`Axes.get_rasterization_zorder` | Get zorder value below which artists will be rasterized
`Axes.set_rasterization_zorder` | Set zorder value below which artists will be rasterized.
`Axes.get_window_extent` | get the axes bounding box in display space; args and
`Axes.get_tightbbox` | Return the tight bounding box of the axes.

## Bulk property manipulation

`Axes.set` | A property batch setter.
`Axes.update` | Update the properties of this `Artist` from the dictionary prop.
`Axes.properties` | return a dictionary mapping property name -> value for all Artist props
`Axes.update_from` | Copy properties from other to self.

## General Artist Properties

`Axes.set_alpha` | Set the alpha value used for blending - not supported on all backends.
`Axes.set_animated` | Set the artist’s animation state.
`Axes.set_clip_box` | Set the artist’s clip `Bbox`.
`Axes.set_clip_on` | Set whether artist uses clipping.
`Axes.set_clip_path` | Set the artist’s clip path, which may be:
`Axes.set_gid` | Sets the (group) id for the artist
`Axes.set_label` | Set the label to s for auto legend.
`Axes.set_url` | Sets the url for the artist
`Axes.set_visible` | Set the artist’s visiblity.
`Axes.set_zorder` | Set the zorder for the artist.
`Axes.set_rasterized` | Force rasterized (bitmap) drawing in vector backend output.
`Axes.set_sketch_params` | Sets the sketch parameters.
`Axes.set_agg_filter` | set agg_filter function.
`Axes.set_snap` | Sets the snap setting which may be:
`Axes.set_transform` | Set the `Transform` instance used by this artist.
`Axes.set_path_effects` | set path_effects, which should be a list of instances of
`Axes.get_agg_filter` | return filter function to be used for agg filter
`Axes.get_sketch_params` | Returns the sketch parameters for the artist.
`Axes.get_alpha` | Return the alpha value used for blending - not supported on all
`Axes.get_animated` | Return the artist’s animated state
`Axes.get_clip_box` | Return artist clipbox
`Axes.get_clip_on` | Return whether artist uses clipping
`Axes.get_clip_path` | Return artist clip path
`Axes.get_gid` | Returns the group id
`Axes.get_label` | Get the label used for this artist in the legend.
`Axes.get_url` | Returns the url
`Axes.get_visible` | Return the artist’s visiblity
`Axes.get_zorder` | Return the `Artist`’s zorder.
`Axes.get_rasterized` | return True if the artist is to be rasterized
`Axes.get_transform` | Return the `Transform` instance used by this artist.
`Axes.get_snap` | Returns the snap setting which may be:
`Axes.get_path_effects` |
`Axes.axes` | The `Axes` instance the artist resides in, or None.
`Axes.get_axes` | Return the `Axes` instance the artist resides in, or None.
`Axes.set_axes` | Set the `Axes` instance in which the artist resides, if any.
`Axes.set_figure` | Set the class:`Axes` figure
`Axes.get_figure` | Return the `Figure` instance the artist belongs to.

## Artist Methods

`Axes.is_figure_set` | Returns True if the artist is assigned to a `Figure`.
`Axes.remove` | Remove the artist from the figure if possible.
`Axes.is_transform_set` | Returns True if `Artist` has a transform explicitly set.

## Projection

Methods used by `Axis` that must be overridden for non-rectilinear Axes.

`Axes.name` |
`Axes.get_xaxis_transform` | Get the transformation used for drawing x-axis labels, ticks and gridlines.
`Axes.get_yaxis_transform` | Get the transformation used for drawing y-axis labels, ticks and gridlines.
`Axes.get_data_ratio` | Returns the aspect ratio of the raw data.
`Axes.get_data_ratio_log` | Returns the aspect ratio of the raw data in log scale.
`Axes.get_xaxis_text1_transform` | Get the transformation used for drawing x-axis labels, which will add the given amount of padding (in points) between the axes and the label.
`Axes.get_xaxis_text2_transform` | Get the transformation used for drawing the secondary x-axis labels, which will add the given amount of padding (in points) between the axes and the label.
`Axes.get_yaxis_text1_transform` | Get the transformation used for drawing y-axis labels, which will add the given amount of padding (in points) between the axes and the label.
`Axes.get_yaxis_text2_transform` | Get the transformation used for drawing the secondary y-axis labels, which will add the given amount of padding (in points) between the axes and the label.

## Other

`Axes.zorder` |
`Axes.aname` |
`Axes.get_default_bbox_extra_artists` |
`Axes.get_transformed_clip_path_and_affine` | Return the clip path with the non-affine part of its transformation applied, and the remaining affine part of its transformation.
`Axes.has_data` | Return True if any artists have been added to axes.
`Axes.hold` | Deprecated since version 2.0.
`Axes.ishold` | Deprecated since version 2.0.

## Inheritance