Fix 'Matplotlib Is Currently Using Agg, A Non-GUI Backend' In Python

If you’ve ever worked with Matplotlib in Python, you might have encountered the warning: “Matplotlib is currently using agg, a non-GUI backend.” I’ve faced this issue many times during my data visualization projects, especially when running scripts on servers or headless environments.

In this tutorial, I’ll walk you through what this message means, why it happens, and several practical ways to resolve it.

What Does “Agg, a Non-GUI Backend” Mean?

Matplotlib uses different backends to render graphics. Some backends are GUI-based, allowing plots to pop up in windows, while others are non-GUI and render images without displaying them on screen. The Agg backend is a non-GUI backend used primarily for generating image files (like PNGs) in environments without a display server.

When you see this message, it means Matplotlib defaulted to the Agg backend because it couldn’t find a suitable GUI backend. This usually happens if you’re running Python on a server without a graphical interface or if your environment variables aren’t set properly.

Check out Matplotlib Save as PNG

Why Does This Happen?

From my experience, this issue commonly arises in these scenarios:

Running Python scripts on a headless server or a cloud environment without a display.
Using remote connections (like SSH) without X forwarding.
Missing GUI libraries or dependencies on your system.
Improper Matplotlib configuration or environment variables.

Understanding the root cause helps in applying the right fix.

Read Matplotlib Bar Chart Labels

How to Fix the “Agg, a Non-GUI Backend” Issue

Let me explain to you the methods to fix the “Agg, a Non-GUI Backend” Issue.

Method 1: Set the Backend Explicitly in Your Script

The simplest way I’ve found to avoid this warning is to explicitly tell Matplotlib which backend to use. If you want to generate image files without displaying windows, Agg is perfect.

Add this line before importing matplotlib.pyplot:

import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt

This approach ensures your script uses the Agg backend intentionally and suppresses the warning. It’s ideal for automated scripts that save plots to files without user interaction.

Read Add Text to Plot Matplotlib in Python

Method 2: Use a GUI Backend for Interactive Plots

If you want to display plots interactively on your local machine, you need to use a GUI backend like TkAgg, Qt5Agg, or MacOSX (depending on your OS).

For example, on Windows or macOS, you can set the backend to TkAgg:

import matplotlib
matplotlib.use('TkAgg')
import matplotlib.pyplot as plt

Make sure you have the required GUI libraries installed:

For TkAgg: Install python3-tk (Linux) or ensure Python includes Tkinter on Windows/macOS.
For Qt5Agg: Install PyQt5 or PySide2 (pip install PyQt5).

This method enables interactive plotting windows without the Agg warning.

Check out Matplotlib Plot Error Bars

Method 3: Check Your Environment Variables and Display Settings

When running on Linux servers or WSL (Windows Subsystem for Linux), the absence of a display server causes Matplotlib to fall back to Agg.

To fix this, you can:

Use X11 forwarding if connected via SSH:

ssh -X user@your-server

Set the DISPLAY environment variable correctly:

export DISPLAY=:0

If you don’t have a graphical environment, you can install a virtual display server like Xvfb:

sudo apt-get install xvfb
xvfb-run python your_script.py

This tricks Matplotlib into thinking a display exists, allowing GUI backends to run.

Method 4: Use Jupyter Notebooks for Inline Plotting

If you’re working in Jupyter notebooks, you don’t usually see the Agg backend warning because plots render inline.

Make sure to include this magic command at the top of your notebook:

%matplotlib inline

This tells Matplotlib to use the inline backend, which works well in notebook environments.

Read Matplotlib Remove Tick Labels

Method 5: Verify Your Matplotlib Configuration File

Matplotlib stores default backend settings in a configuration file (matplotlibrc). Sometimes, this file forces a non-GUI backend.

You can check the current backend by running:

import matplotlib
print(matplotlib.get_backend())

You can see the output in the screenshot below.

If it returns agg, you might want to edit or override the config file. The config file location can be found by:

import matplotlib
print(matplotlib.matplotlib_fname())

You can see the output in the screenshot below.

matplotlib is currently using agg which is a non-gui backend

Open this file and look for the backend setting. Change it to your preferred GUI backend like TkAgg or comment it out to let Matplotlib choose automatically.

The “Matplotlib is currently using agg, a non-GUI backend” message is a common one, especially when working in non-GUI environments. From my experience, the best approach depends on your use case:

If you want to save plots to files without displaying them, explicitly use the Agg backend.
For interactive plots on your local machine, switch to a GUI backend like TkAgg or Qt5Agg.
When working on remote servers, consider using X11 forwarding or virtual displays.
In Jupyter notebooks, use %matplotlib inline for seamless plotting.

By understanding the backend system and applying these simple solutions, you can avoid this warning and ensure that your Matplotlib visualizations work exactly as intended.