Matplotlib
The foundational Python plotting library — verbose, and capable of almost any figure.
What it is
Matplotlib is a comprehensive 2D plotting library for Python. It allows the creation of high-quality graphs, charts, and figures in various formats, suitable for publication and interactive visualization.
Matplotlib allows you to create line plots, scatter plots, bar charts, histograms, 3D plots, and more. The library provides both an object-oriented interface and a state-based interface (pyplot) to build plots programmatically or interactively.
- Watch for
- Two APIs coexist — prefer the object-oriented `fig, ax` style over `pyplot` state
- Licence
- PSF-based
When to use it
The question documentation cannot answer for you — because it cannot recommend something else.
Reach for it when
- Publication-quality static figures with exact control over every element
- You need a chart type or annotation that higher-level libraries do not expose
Look elsewhere when
- You want attractive statistical plots quickly — Seaborn wraps this in far less code
- The chart needs to be interactive in a browser — use Plotly or Bokeh
Installation
pip install matplotlibGetting started
The smallest useful thing you can do with it, and what each part means.
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [2, 3, 5])
plt.xlabel('X-axis')
plt.ylabel('Y-axis')
plt.title('Simple Line Plot')
plt.show()import matplotlib.pyplot as plt
x = [1, 2, 3, 4]
y = [10, 20, 25, 30]
plt.scatter(x, y, color='red', marker='x')
plt.show()Advanced usage
Where the library earns its place over a simpler alternative.
import matplotlib.pyplot as plt
fig, axs = plt.subplots(2, 1)
axs[0].plot([1,2,3],[1,4,9])
axs[1].bar([1,2,3],[5,2,7])
plt.show()import matplotlib.pyplot as plt
plt.style.use('ggplot')
plt.plot([1,2,3],[1,4,9])
plt.show()from mpl_toolkits.mplot3d import Axes3D
import matplotlib.pyplot as plt
import numpy as np
fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')
x = np.linspace(0,5,100)
y = np.sin(x)
z = np.cos(x)
ax.plot(x,y,z)
plt.show()import matplotlib.pyplot as plt
data = [1,1,2,3,3,3,4,4,5]
plt.hist(data, bins=5, color='purple', alpha=0.7)
plt.show()Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- ValueError: x and y must have same first dimension
- Ensure your x and y data arrays have the same length.
- ImportError: mpl_toolkits not found
- Install Matplotlib fully and ensure the toolkit is available for 3D plots.
Best practices
- Use the object-oriented interface for complex plots for more control.
- Label axes and add titles to improve readability.
- Use grid lines and legends where appropriate.
- Combine Matplotlib with NumPy for efficient data plotting.
- Save figures using `plt.savefig()` for reproducibility.
Alternatives
Comparable options, and the reason you would pick one over the other.
Background
Why it exists, and what it was reacting to.
Matplotlib was originally created by John D. Hunter in 2003 to provide a MATLAB-like plotting interface for Python. It has become the foundation for many Python visualization libraries, including Seaborn and Pandas plotting utilities, and remains widely used in data analysis, scientific research, and machine learning.