import matplotlib.pyplot as plt: What It Does

import matplotlib.pyplot as plt loads Matplotlib’s pyplot interface under the short name plt, which is the import used throughout the Matplotlib documentation. Run it once at the top of a script or notebook, then call figure-building functions such as plt.subplots() and plt.show() through plt. This guide covers what the line does, how to confirm Matplotlib is installed in the Python you are actually running, and how to fix the common cases where nothing appears or the import fails.

What it is used for in research

Matplotlib is the plotting library behind most figures in Python-based analysis, and import matplotlib.pyplot as plt is how a script gets access to it. The Matplotlib quick-start page uses exactly this line, together with import numpy as np, as its import block. Other libraries refer to the same convention: the pandas visualization guide states “We use the standard convention for referencing the matplotlib API” and then shows import matplotlib.pyplot as plt, and its plot method on a Series or DataFrame is described as a simple wrapper around plt.plot().

For research workflows, that means one import line serves hand-built figures, quick exploratory plots from a DataFrame, and statistical graphics drawn with seaborn, which builds on top of Matplotlib. See Python for exploratory data analysis for how plotting fits into a wider analysis workflow.

The import variants, side by side

The searches “import matplotlib”, “how to import matplotlib” and “matplotlib import” all point to the same family of lines.

• import matplotlib.pyplot as plt is the import block on the Matplotlib quick-start page. It is the line to use for plotting.
• import matplotlib loads the top-level package. The installation page uses it to check the install (matplotlib.__version__), and the quick-start page itself has no standalone import matplotlib line.
• import matplotlib as mpl is the form the installation page uses to reach configuration helpers such as mpl.get_configdir() and mpl.get_cachedir().
• from pylab import * appears in older examples. The quick-start page calls this approach “strongly deprecated”.

Install or access (official source only)

Matplotlib’s installation page lists these commands. Use the one that matches how you manage Python environments:

• pip: python -m pip install -U pip, then python -m pip install -U matplotlib
• conda: conda install -c conda-forge matplotlib (the page also lists conda install matplotlib)
• pixi: pixi add matplotlib
• uv: uv add matplotlib

Two notes from the same page. If pip tries to compile Matplotlib from source and fails, add --prefer-binary. If you use uv, the page says to use uv 0.8.7 or newer, otherwise the TkAgg backend may not work; the alternative it gives is uv add matplotlib pyside6.

Step-by-step: import and first figure

1. Install Matplotlib into the environment you will run your code in, using one of the commands above.
2. Put the import at the top of your script or notebook cell:

   import matplotlib.pyplot as plt
   import numpy as np

3. Create a Figure and Axes, then plot on the Axes:

   fig, ax = plt.subplots()
   ax.plot([1, 2, 3, 4], [1, 4, 2, 3])
   plt.show()

4. Run the script (not an interactive shell or IDLE, see troubleshooting below) and check that a window opens or, in a notebook, that the figure appears under the cell.

Why import pyplot at all, and which style to use

The quick-start page says there are essentially two ways to use Matplotlib: explicitly create Figures and Axes and call methods on them (the object-oriented, or OO, style), or rely on pyplot to implicitly create and manage Figures and Axes and use pyplot functions for plotting. Its guidance is to use the OO style “particularly for complicated plots, and functions and scripts that are intended to be reused as part of a larger project”, while the pyplot style “can be very convenient for quick interactive work”. Even in the OO style, the page notes, you still use pyplot.figure to create the Figure, so the import is needed either way. The example in step 3 is the OO style.

Do I need plt.show()?

Often yes in a script, often no in a notebook. The quick-start page says that, depending on the environment, plt.show() can be left out, for example in Jupyter notebooks, which automatically show all figures created in a code cell. The seaborn introduction makes the related point that for interactive work a Jupyter/IPython interface in matplotlib mode is recommended, or else you have to call matplotlib.pyplot.show() to see the plot.

Output and how to read it

A successful import prints nothing. To confirm which Matplotlib you are importing, the installation page gives this check:

python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)'

In an interactive session you can run import matplotlib and then matplotlib.__version__. Read the two values like this:

• The version tells you which Matplotlib release the environment holds, which matters when documentation or an example you are following is written for a different release.
• The file path tells you where that copy lives on disk, so you can tell whether Python is picking up the environment you meant (a project virtual environment, a conda environment) or a different install.

Matplotlib also keeps configuration and cache directories. import matplotlib as mpl followed by mpl.get_configdir() or mpl.get_cachedir() prints them, and the environment variable MPLCONFIGDIR sets both.

Troubleshooting

ModuleNotFoundError: Matplotlib is not installed in the active environment

When a module cannot be located, Python raises ModuleNotFoundError, which the Python documentation describes as a subclass of ImportError raised by import when a module could not be located. In practice this means the Python running your code does not have Matplotlib. Install it with the commands above into that same interpreter, then re-run the version check to confirm.

Importing from the wrong Python

The installation page warns that on macOS, if which python3 returns a path beginning /usr/bin/python, you are using the system Python, which is probably not what you want. Compare the file path printed by the version check with the environment you intended to use.

The code runs but no figure appears

The installation page’s advice is to run a script rather than an interactive shell or IDLE. To see which backends are loaded, it suggests running python -c "from pylab import *; set_loglevel('DEBUG'); plot(); show()". It also notes that the non-interactive backends Agg, ps, pdf and svg work out of the box, while TkAgg typically works if Tk bindings (tkinter) are present, and some operating systems need a separate package such as python3-tk.

TkAgg backend not working with uv

See the uv note under installation: use uv 0.8.7 or newer, or add a different GUI package with uv add matplotlib pyside6.

Alternatives and wrappers

Seaborn and pandas plotting build on or wrap Matplotlib rather than replacing it, so the import above remains relevant.

Option	Import convention	Relationship to Matplotlib (per its docs)
seaborn	import seaborn as sns	Described in its introduction as a library for statistical graphics that builds on top of matplotlib and integrates closely with pandas data structures.
pandas plotting	df.plot() after import pandas as pd	The plot method on Series and DataFrame is a simple wrapper around plt.plot().

For a head-to-head view of the two most common choices, read seaborn vs matplotlib. To see the import in use, the guides on a scatter plot in Python, a colorbar in matplotlib, a legend in matplotlib and a heatmap in seaborn each start from it.

FAQ

How do I import matplotlib?

For plotting, write import matplotlib.pyplot as plt at the top of your script or notebook, after installing Matplotlib into the environment you run. Use import matplotlib on its own when you only need the package itself, such as to print matplotlib.__version__.

Why import matplotlib.pyplot as plt?

The as plt alias is the standard convention for referencing the Matplotlib API, as the pandas visualization guide puts it, and it is the form the Matplotlib quick-start uses. The import itself is needed because pyplot is how you create the Figure, in both the OO and pyplot styles.

What is the difference between import matplotlib and import matplotlib.pyplot?

import matplotlib loads the top-level package, which the documentation uses for version and configuration checks. import matplotlib.pyplot as plt loads the pyplot interface used to create Figures and Axes and to plot.

Do I need plt.show()?

In a script, generally yes. In Jupyter notebooks it can be left out because figures created in a code cell are shown automatically.

How do I check which Matplotlib version is installed?

Run python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)'. It prints the version and the file location of the copy being imported.

Sources

• Matplotlib, Quick-start guide (stable docs, Matplotlib 3.11.2), https://matplotlib.org/stable/users/explain/quick_start.html, checked 2026-10-29.
• Matplotlib, Installation, https://matplotlib.org/stable/install/index.html, checked 2026-10-29.
• seaborn, An introduction to seaborn, https://seaborn.pydata.org/tutorial/introduction.html, checked 2026-10-29.
• pandas, Chart visualization (user guide), https://pandas.pydata.org/docs/user_guide/visualization.html, checked 2026-10-29.
• Python documentation, Built-in exceptions (ModuleNotFoundError), https://docs.python.org/3/library/exceptions.html, checked 2026-10-29.