Written and maintained by CASRAI Editorial Board
Last updated
To install Matplotlib with pip, run python -m pip install matplotlib in the same Python environment you will plot from. The official Matplotlib documentation gives pip install matplotlib as its first install option, and writing it as python -m pip ties the install to the interpreter you name, so the package lands where your scripts run. This guide covers the command, a virtual environment setup, the Python and NumPy floor, how to check the install, and what to do when pip builds from source or no plot window appears. Searches for “matplotlib pip” are the same task and are covered in the sections below.
What it is used for in research
Matplotlib is the Python library behind most static research figures: line plots, scatter plots, histograms, contour plots and the figures that pandas and seaborn draw underneath. Installing it is the first step for any plotting work in the CASRAI guides on import matplotlib.pyplot as plt, marker size in Matplotlib, line width in Matplotlib and contour plots in Matplotlib.
Install or access (official source only)
The Matplotlib installation page (matplotlib.org/stable/install, checked 2026-10-29, documentation for Matplotlib 3.11.2) gives this command:
pip install matplotlibThe Python Packaging User Guide (packaging.python.org, “Installing packages”, checked 2026-10-29) recommends invoking pip through the interpreter and doing the install inside a virtual environment. The commands below follow that guide, with Matplotlib as the package.
1. Create and activate a virtual environment
- Unix and macOS:
python3 -m venv .venv, thensource .venv/bin/activate - Windows:
py -m venv .venv, then.venv\Scripts\activate
The folder name .venv is a choice; the guide uses a placeholder for the directory.
2. Check pip and, if needed, update it
Check the version with python3 -m pip --version (Windows: py -m pip --version). The Matplotlib page gives python -m pip install -U pip to update pip itself.
Python and NumPy requirements
According to the dependencies page for the current stable documentation (checked 2026-10-29), Matplotlib needs Python 3.11 or newer and NumPy 1.25 or newer. Its other mandatory dependencies are contourpy, cycler, python-dateutil, fontTools, kiwisolver, packaging, Pillow and pyparsing. When you install through pip or conda, the page states that the mandatory dependencies are installed automatically, so you do not install them by hand. These minimum versions change between releases, so check the dependencies page for the release you are installing.
Step-by-step task
- Activate your virtual environment (see above).
- Install:
python -m pip install matplotlib - Upgrade later, when you want a newer release:
python -m pip install -U matplotlib - Confirm which copy Python loads (next section).
- Draw a first figure in a script and run the script. NumPy usage is covered in import numpy as np, and the module guide explains what the import statement is loading.
Output and how to read it
A successful pip run ends by listing the packages it installed. To confirm the install, the Matplotlib page shows two attributes, matplotlib.__version__ and matplotlib.__file__, and a one-line check:
python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)'The first value is the installed version. The second is the path Python imported it from. If that path points outside your virtual environment, a different Python is running than the one you installed into; activate the environment or call that interpreter explicitly with python -m pip.
Troubleshooting
pip tries to build Matplotlib from source and fails
The installation page says that if a source build fails you can add --prefer-binary, which selects the newest Matplotlib version that has a precompiled wheel for your operating system and Python:
python -m pip install --prefer-binary matplotlibAlso compare your Python and NumPy versions against the dependencies page above.
The script runs but no plot window appears
- The documentation recommends running a script rather than using IDLE or an interactive shell, and trying a clean install.
- The TkAgg backend needs Tk bindings, usually supplied by the standard library
tkintermodule. On some operating systems you may need a separate package such aspython3-tk. - The non-interactive backends Agg, ps, pdf and svg work out of the box, so saving a figure to a file works without a window.
- To see which backend is chosen, the page gives:
python -c "from pylab import *; set_loglevel('DEBUG'); plot(); show()"
Where Matplotlib keeps its configuration and cache
Run mpl.get_configdir() and mpl.get_cachedir() (after import matplotlib as mpl) to print the two folders. Setting the MPLCONFIGDIR environment variable moves both.
macOS
The installation page notes that Apple’s system Python is hard to upgrade and recommends installing a fresh Python instead.
Free alternatives (table)
The same page lists other ways to get Matplotlib. The commands below are as listed on that page.
| Tool | Command from the Matplotlib install page | Note from the page |
|---|---|---|
| conda | conda install -c conda-forge matplotlib |
Installs from the conda-forge channel |
| pixi | pixi add matplotlib |
Listed on the same page |
| uv | uv add matplotlib |
For TkAgg, the page says to use uv 0.8.7 or newer |
| Debian / Ubuntu | sudo apt-get install python3-matplotlib |
For the distribution’s own Python |
| Fedora | sudo dnf install python3-matplotlib |
For the distribution’s own Python |
| Arch | sudo pacman -S python-matplotlib |
For the distribution’s own Python |
FAQ
What is the pip command for Matplotlib?
pip install matplotlib, or python -m pip install matplotlib to be sure it goes to the interpreter you name.
How do I upgrade Matplotlib with pip?
Run python -m pip install -U matplotlib. Update pip first with python -m pip install -U pip if the upgrade fails.
How do I check which version I installed?
Print matplotlib.__version__. The one-line command in the output section prints the version and the install path together.
Does pip install the other packages Matplotlib needs?
Yes. The dependencies page states that installing through pip or conda installs the mandatory dependencies automatically.
Why does pip say it must build from source?
No precompiled wheel matched your system. Add --prefer-binary to pick the newest version that has one, and check your Python version against the dependencies page.
Sources (official docs)
- Matplotlib, Installation: matplotlib.org/stable/install/index.html (checked 2026-10-29)
- Matplotlib, Dependencies: matplotlib.org/stable/install/dependencies.html (checked 2026-10-29)
- Python Packaging User Guide, Installing packages: packaging.python.org/en/latest/tutorials/installing-packages (checked 2026-10-29)
