# API Overview

See also the API Changes (opens new window).

# Usage patterns

Below we describe several common approaches to plotting with Matplotlib.

# The pyplot API

matplotlib.pyplot (opens new window) is a collection of command style functions that make Matplotlib work like MATLAB. Each pyplot function makes some change to a figure: e.g., creates a figure, creates a plotting area in a figure, plots some lines in a plotting area, decorates the plot with labels, etc.

pyplot (opens new window) is mainly intended for interactive plots and simple cases of programmatic plot generation.

Further reading:

# The object-oriented API

At its core, Matplotlib is object-oriented. We recommend directly working with the objects, if you need more control and customization of your plots.

In many cases you will create a Figure (opens new window) and one or more Axes (opens new window) using pyplot.subplots (opens new window) and from then on only work on these objects. However, it's also possible to create Figure (opens new window)s explicitly (e.g. when including them in GUI applications).

Further reading:

# The pylab API (disapproved)

Warning

Since heavily importing into the global namespace may result in unexpected behavior, the use of pylab is strongly discouraged. Use matplotlib.pyplot (opens new window) instead.

pylab is a module that includes matplotlib.pyplot (opens new window), numpy (opens new window) and some additional functions within a single namespace. Its original purpose was to mimic a MATLAB-like way of working by importing all functions into the global namespace. This is considered bad style nowadays.

# Modules

Matplotlib consists of the following submodules:

# Toolkits

Toolkits (opens new window) are collections of application-specific functions that extend Matplotlib. The following toolkits are included: