How to install Matplotlib in a Python virtual environment

Project-local Python environments keep plotting dependencies away from the system interpreter and from other applications. For Matplotlib, a virtual environment fits scripts and notebooks that need packages from PyPI without changing the rest of the machine.

venv creates an isolated interpreter directory, and python -m pip installs packages into whichever interpreter is active. Running pip through Python avoids accidentally using a different pip command from the shell.

The primary path uses a Unix-style shell with Python 3.11 or newer, which matches current Matplotlib requirements. Windows PowerShell uses .venv\Scripts\Activate.ps1 instead of the Unix activation path, while the same python -m pip commands apply after activation.

1. Open a terminal in the project directory that should own the environment.
2. Create the virtual environment with Python 3.11 or newer.

   $ python3 -m venv .venv

   On Windows, use py -m venv .venv from PowerShell or Command Prompt.

3. Activate the virtual environment.

   $ . .venv/bin/activate

   On Windows PowerShell, use .venv\Scripts\Activate.ps1. If local policy blocks activation scripts, run the environment interpreter directly as .venv\Scripts\python.exe.

4. Upgrade pip inside the active environment.

   $ python -m pip install --upgrade pip

5. Install Matplotlib and its required dependencies.

   $ python -m pip install --upgrade matplotlib

   pip installs Matplotlib dependencies such as NumPy, Pillow, contourpy, and python-dateutil automatically when compatible wheels are available.

6. Confirm that the active interpreter imports Matplotlib.

   $ python -c "import matplotlib; print(matplotlib.__version__)"
   3.11.0

   The exact version changes over time. The command should run without an import error and print the version installed in the active virtual environment.

7. Save a file-only smoke test as verify_matplotlib.py.

   verify_matplotlib.py

   from pathlib import Path
    
   import matplotlib
    
   matplotlib.use("Agg")
   import matplotlib.pyplot as plt
    
   output = Path("venv-matplotlib-smoke.png")
    
   fig, ax = plt.subplots(layout="constrained")
   ax.plot([1, 2, 3], [1, 4, 9], marker="o")
   ax.set_title("Virtual environment smoke test")
   ax.set_xlabel("Run")
   ax.set_ylabel("Value")
   fig.savefig(output)
   plt.close(fig)
    
   print(f"matplotlib {matplotlib.__version__}")
   print(f"backend {matplotlib.get_backend()}")
   print(f"saved: {output}")
   print(f"bytes: {output.stat().st_size}")

   The Agg backend writes image files without opening a desktop window, which keeps the smoke test usable in terminals, containers, and remote shells.

8. Run the smoke test from the active virtual environment.

   $ python verify_matplotlib.py
   matplotlib 3.11.0
   backend Agg
   saved: venv-matplotlib-smoke.png
   bytes: 25942

   The byte count varies by Matplotlib version, font rendering, and platform. Confirm the version line, Agg backend, saved filename, and a nonzero byte count.

9. Open the saved image and confirm the line chart was written.
10. Remove the smoke-test files if they were created only for verification.

    $ rm verify_matplotlib.py venv-matplotlib-smoke.png

11. Leave the virtual environment shell when finished.

    $ deactivate