| name | matplotlib-3-11-0 |
| description | Matplotlib plotting library (v3.11). Use this skill whenever the user mentions plots, charts, graphs, figures, data visualization, matplotlib, pyplot, or needs to create any kind of visual output from Python data — line plots, scatter plots, bar charts, histograms, heatmaps, contour plots, subplots, legends, colormaps, saving figures, styling, animations, or interactive widgets. Covers both the pyplot (state-based) and object-oriented APIs.
|
matplotlib 3.11.0
Overview
Matplotlib is Python's foundational plotting library. It provides two interfaces:
- pyplot (state-based) —
plt.plot(), plt.show(). MATLAB-like, convenient for interactive work and quick scripts.
- Object-oriented (OO) —
fig, ax = plt.subplots(); ax.plot(). Explicit control over every element. Preferred for complex plots and production code.
The core hierarchy is: Figure → Axes → Artist (lines, patches, text, images). Most pyplot functions are thin wrappers around Axes methods.
Usage
Quick start (pyplot)
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
plt.plot(x, np.sin(x), label='sin')
plt.xlabel('x'); plt.ylabel('y')
plt.legend(); plt.tight_layout()
plt.savefig('plot.png', dpi=150)
plt.show()
Object-oriented (preferred for complex plots)
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(x, np.sin(x), label='sin')
ax.plot(x, np.cos(x), label='cos')
ax.set_xlabel('x'); ax.set_ylabel('y')
ax.legend(); fig.tight_layout()
fig.savefig('plot.png', dpi=150, bbox_inches='tight')
Multiple subplots
fig, axes = plt.subplots(2, 3, figsize=(12, 8), sharex=True)
fig, axd = plt.subplot_mosaic([
['top_left', 'top_right'],
['bottom', 'bottom'],
], figsize=(10, 6))
fig, axes = plt.subplots(2, 2, constrained_layout=True)
Key OO methods on Axes
| Task | Method |
|---|
| Line plot | ax.plot(x, y, label='...', color='C0', linewidth=2) |
| Scatter | ax.scatter(x, y, c=colors, s=sizes, cmap='viridis') |
| Bar chart | ax.bar(x, height, width=0.8, color='steelblue') |
| Horizontal bar | ax.barh(y, width, left=None) |
| Histogram | ax.hist(data, bins=30, density=False, alpha=0.7) |
| Fill between | ax.fill_between(x, y1, y2, alpha=0.3) |
| Error bars | ax.errorbar(x, y, yerr=err, capsize=4) |
| Box plot | ax.boxplot(data, patch_artist=True) |
| Violin plot | ax.violinplot(data) |
| Pie chart | ax.pie(sizes, labels=labels, autopct='%.1f%%') |
| Heatmap | ax.imshow(Z, cmap='viridis', aspect='auto') |
| Contour | ax.contour(X, Y, Z, levels=10) / ax.contourf(...) |
| Pcolormesh | ax.pcolormesh(X, Y, Z, shading='auto', cmap='viridis') |
| Stem plot | ax.stem(x, y, linefmt='C0-', markerfmt='o') |
| Quiver (vector) | ax.quiver(x, y, u, v) |
| Streamplot | ax.streamplot(X, Y, U, V) |
| Hexbin | ax.hexbin(x, y, C, gridsize=20, cmap='Blues') |
| Text | ax.text(x, y, 'label', fontsize=12) |
| Annotate | ax.annotate('text', xy=(x,y), xytext=(tx,ty), arrowprops=dict(...)) |
| Title | ax.set_title('Title', fontsize=14, fontweight='bold') |
| Labels | ax.set_xlabel('X'); ax.set_ylabel('Y') |
| Limits | ax.set_xlim(0, 10); ax.set_ylim(-1, 1) |
Gotchas
plt.plot() without explicit axes draws on the "current" axes, which can silently target the wrong subplot in multi-figure scripts. Always use fig, ax = plt.subplots() for reliability.imshow vs pcolormesh: imshow maps array indices to pixel centers (default origin='upper'), while pcolormesh maps to grid corners. For heatmaps with labeled axes, pcolormesh is usually more intuitive. Use shading='auto' on pcolormesh for correct alignment.- Colormap normalization: If colors look wrong, check that
vmin/vmax are set explicitly. Without them, matplotlib auto-scales to data min/max which can be misleading when comparing multiple plots.
tight_layout() vs constrained_layout: tight_layout() runs once at call time; constrained_layout=True (or layout='constrained') is reactive and adjusts as elements are added. Prefer constrained_layout for complex figures.- Backend selection must happen before any figure creation. Call
matplotlib.use('Agg') or set MPLBACKEND=Agg before importing pyplot if running headless (no display).
- DPI confusion:
figsize is in inches, savefig(dpi) controls output resolution. A 6×4 inch figure at 100 dpi = 600×400 pixels. For publication, use dpi=300 or bbox_inches='tight'.
- Legend overlaps data: Use
loc='best' for auto-placement, or bbox_to_anchor=(x, y) with loc to position outside the axes area.
- Shared axes:
sharex=True / sharey=True in subplots() links axis limits and removes redundant tick labels. But calling ax.set_xlim() on one shared axis affects all of them.
- Markers are not clipped by default — large markers can extend beyond axis boundaries. Use
clip_on=True or adjust margins with ax.margins(x=0.05, y=0.05).
References
Detailed topic guides loaded on demand:
- 01-core-api — Figure/Axes/Artist hierarchy, pyplot vs OO, backends
- 02-plot-types — Line, scatter, bar, histogram, area, errorbar, stem, pie
- 03-layout — subplots, gridspec, subplot_mosaic, constrained_layout
- 04-colors-and-colormaps — Color specs, colormaps, normalization, color sequences
- 05-text-and-annotations — Text, titles, labels, annotations, math text, fonts
- 06-ticks-and-axes — Locators, formatters, scales, spines, twin axes
- 07-legend-and-colorbar — Legends, colorbars, custom handles
- 08-patches-and-shapes — Rectangle, Circle, Polygon, Arrow, FancyBboxPatch
- 09-transforms — Coordinate systems, Affine2D, blitting
- 10-styling-and-themes — rcParams, style.use(), contexts, custom styles
- 11-dates-and-times — Date plotting, locators, formatters, timezones
- 12-image-and-contour — imshow, pcolormesh, contour, quiver, streamplot
- 13-animation-and-widgets — FuncAnimation, widgets (Slider, Button, Cursor)
- 14-saving-and-exporting — savefig formats, DPI, vector vs raster, PDF/SVG
