What Matplotlib is and why you need it installed

Matplotlib is a Python library that turns data into charts and graphs. If you write Python code that works with numbers, measurements, or any information you want to visualize, Matplotlib lets you create line graphs, bar charts, scatter plots, and histograms without building the graphing tool yourself.

Installing Matplotlib means adding it to your Python environment so that your code can call it. This is different from installing a program you click on — you are adding a toolkit that your Python scripts can use. The installation process depends on what operating system you use and whether you already have Python set up.

Key Takeaways

  • Matplotlib installs through pip, the Python package manager, using a single command in your terminal or command prompt.
  • You must have Python and pip already installed before you can install Matplotlib; if you do not, install Python first from python.org.
  • The command pip install matplotlib works on Windows, macOS, and Linux, though the terminal process you use differs by system.
  • After installation, test that Matplotlib works by running a short Python script that creates a straightforward graph.
  • If the installation fails, the most common cause is pip pointing to the wrong Python version or not being in your system path.

Check that Python and pip are already on your computer

Before you install Matplotlib, confirm that Python is installed and that pip (the package installer) works. Open your terminal or command prompt and type the command that matches your operating system.

On macOS or Linux, open Terminal and type:

python3 --version

On Windows, open Command Prompt or PowerShell and type:

python --version

If you see a version number like "Python 3.9.0" or higher, Python is installed. Next, check pip by typing:

pip --version

If you see a version number and a path, pip is ready. If either command returns "command not found" or "is not recognized", you need to install Python first from python.org before continuing.

Install Matplotlib using pip

Once Python and pip are confirmed working, installing Matplotlib takes one command. Open your terminal or command prompt and type:

pip install matplotlib

Press Enter and wait. Pip will read Matplotlib and its dependencies (other libraries it needs to work) and install them automatically. The process usually takes one to three minutes depending on your internet speed.

When the installation finishes, you will see a message that says "Successfully installed matplotlib" followed by a version number. If you see an error instead, skip to the troubleshooting section below.

Verify the installation with a test script

After installation completes, create a straightforward Python script to confirm Matplotlib works. Open a text editor, create a new file, and type the following code:

import matplotlib.pyplot as plt plt.plot([1, 2, 3, 4], [1, 4, 2, 3]) plt.show()

Save the file with a name like test_matplotlib.py. Then open your terminal or command prompt, navigate to the folder where you saved the file, and run:

python test_matplotlib.py

On macOS or Linux, you may need to use python3 instead of python. A window should appear showing a straightforward line graph. If it does, Matplotlib is installed and working correctly. Close the window and delete the test file.

Troubleshooting installation problems

If the installation failed or the test script did not work, the issue is usually one of three things. First, check that you are using the correct Python version. If you have both Python 2 and Python 3 on your computer, pip might be connected to Python 2, which is too old for modern Matplotlib. Type:

pip3 install matplotlib

Using pip3 explicitly tells your computer to use the Python 3 version of pip. If that works, remember to use pip3 for future installations.

Second, pip might not be in your system path, meaning your terminal cannot find it even though it is installed. On Windows, try running Command Prompt as Administrator: right-click Command Prompt, select "Run as administrator", and then type the pip install command again.

Third, your computer might block pip from downloading files. If you see an error about SSL certificates or network access, you may be behind a corporate firewall or proxy. Contact your network administrator for the proxy settings, or try installing Matplotlib offline by downloading a wheel file from pypi.org and installing it locally — this is an advanced step, and most home users will not need it.

Installing Matplotlib in a virtual environment

If you work on multiple Python projects, you may want to install Matplotlib in a virtual environment instead of globally. A virtual environment is a separate folder on your computer where each project keeps its own copy of Python libraries, so different projects do not interfere with each other.

To create a virtual environment, open your terminal or command prompt and type:

python -m venv myenv

Replace myenv with whatever name you want. Then set up it. On macOS or Linux, type:

source myenv/bin/set up

On Windows, type:

myenv\Scripts\set up

Your terminal prompt will change to show the environment name. Now type pip install matplotlib as usual. Matplotlib will install only in this environment. When you are done working, type deactivate to exit the environment.

Frequently Asked Questions

Do I need to install Matplotlib if I use Jupyter Notebook or Anaconda?

Anaconda includes Matplotlib by default, so you do not need to install it separately. Jupyter Notebook does not include it, but you can install it the same way using pip install matplotlib or conda install matplotlib if you have Anaconda. Check what you have installed before assuming you need to add Matplotlib.

What if I get a permission denied error during installation?

On macOS or Linux, this usually means pip is trying to install globally and your user account does not have permission. Use pip install --user matplotlib to install just for your account, or create a virtual environment and install there instead. Avoid using sudo with pip, as it can cause permission problems later.

Can I install a specific version of Matplotlib?

Yes. Type pip install matplotlib==3.5.2 to install version 3.5.2, or pip install matplotlib>=3.5 to install version 3.5 or newer. Most users should install the latest version by typing pip install --upgrade matplotlib.

Why does my test script show an error about a display or backend?

This usually happens on remote servers or systems without a graphical display. Matplotlib needs a way to show windows. Add this line at the very top of your script before importing Matplotlib: import matplotlib; matplotlib.use('Agg'). This tells Matplotlib to save graphs to files instead of trying to display them on screen.