Installation and Setup

Matplotlib installs as a single package and works from the first import. Setup decisions that matter are the environment (plain script, Jupyter, or headless server) and the backend that follows from it; everything else is optional configuration covered in the styling chapter.

Install

pip install matplotlib

# verify the install and the backend in use
python -c "import matplotlib; print(matplotlib.__version__, matplotlib.get_backend())"

Recent releases (3.8+) ship with wheels for all major platforms, so no system dependencies are needed. On Linux with no display, it falls back to the non-interactive Agg backend automatically; on a desktop it picks TkAgg or the platform default.

Setting Up in Jupyter

In a notebook you want plots rendered inline (static) or with interactive widgets (pan, zoom, inspect points) directly in the browser:

# static inline images (the classic behavior)
%matplotlib inline

# interactive: pan/zoom/inspect without a browser round trip
%matplotlib widget

Either magic must be the first plotting line of the notebook. %matplotlib widget needs the ipywidgets package (pip install ipywidgets) and works in classic and JupyterLab; in VS Code and Google Colab the inline renderer is already wired up and the magic is optional.

Headless Servers

import matplotlib
matplotlib.use("Agg")            # before importing pyplot
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [4, 1, 2])
fig.savefig("out.png", dpi=150)  # no window, no display needed
plt.close(fig)

On a server without an X display, call matplotlib.use("Agg") before import matplotlib.pyplot and call plt.close(fig) (or plt.close("all")) after saving - open figures accumulate in memory in a long-running process. This is the standard pattern for generating chart images in web services and batch jobs.

A Smoke Test

import matplotlib.pyplot as plt

x = [0, 1, 2, 3, 4]
y = [v * v for v in x]

fig, ax = plt.subplots(figsize=(5, 3))
ax.plot(x, y, marker="o")
ax.set_title("smoke test")
fig.savefig("smoke.png")
print("saved")

If this file exists and opens, the stack works: library, backend, and file output. From here the tutorial assumes a working install and focuses on the API.

Summary

Install with pip, use %matplotlib inline or %matplotlib widget in notebooks, and matplotlib.use("Agg") plus plt.close on headless servers. Run the smoke test once per environment - it catches backend and version problems in ten seconds instead of inside your first real figure.