Matplotlib FigureCanvasAgg Non-interactive Warning

Problem Statement

When using Matplotlib to display plots in Python, you may encounter the warning:

UserWarning: FigureCanvasAgg is non-interactive, and thus cannot be shown plt.show()

This occurs when Matplotlib's backend is set to 'Agg', which is a non-interactive backend designed for generating images for file output rather than displaying plots in an interactive window.

Common Scenarios

• Setting backend explicitly with matplotlib.use('Agg')
• Using environments where default GUI libraries are unavailable (IDEs, headless systems)
• Installing Python without optional GUI libraries like Tkinter
• Running scripts in environments without supported display systems

The warning appears when you try to display a plot interactively with plt.show() while using a non-interactive backend, preventing the plot from appearing and potentially disrupting your workflow.

Solutions

1. Use Interactive Backend Instead of Agg (Recommended)

Remove the non-interactive backend setting and use a default interactive backend:

import numpy as np
import matplotlib.pyplot as plt  # Remove explicit backend setting

# ... rest of your plotting code ...

plt.show()  # Will now display interactively

Why this works: Matplotlib automatically selects an appropriate interactive backend when you don't specify one. The default backend varies by OS but typically includes TkInter on Windows/macOS and Qt on Linux systems.

2. Install Required GUI Dependencies

If removing the backend setting doesn't resolve the issue, install these dependencies appropriate for your operating system and Python version:

Windows/macOS (Python ≤3.11):

pip install PyQt5

import matplotlib
matplotlib.use('Qt5Agg')  # Use this before importing pyplot
import matplotlib.pyplot as plt

Modern systems (Python ≥3.12):

pip install PyQt6

import matplotlib
matplotlib.use('QtAgg')  # QtAgg automatically uses PyQt6/PySide6
import matplotlib.pyplot as plt

Linux (Ubuntu/Debian):

sudo apt-get install python3-tk

3. Configure Backend Globally (Advanced)

Set a permanent default interactive backend in your matplotlib configuration:

1. Find your configuration file path:

   import matplotlib
   print(matplotlib.matplotlib_fname())

2. Open the printed configuration file location

3. Uncomment/modify the backend line:

   backend: TkAgg  # or Qt5Agg/QtAgg

Explanation of Backend Options

Interactive Backends

• TkInter (TkAgg): Default for most Python installations
• PyQt (Qt5Agg/QtAgg): More feature-rich alternative
• GTK/GKCAgg: Linux-centric option
• WebAgg: Browser-based plotting

Non-interactive Backends

• Agg: For PNG output
• PS: PostScript output
• SVG: Scalable Vector Graphics
• PDF: PDF file output

⚠️ Important Notes

1. The matplotlib.use() call must always appear before importing pyplot
2. Different Python versions have different GUI package compatibility:

   | Python Version | Recommended Package |
   |----------------|--------------------|
   | ≤ 3.11         | PyQt5              |
   | ≥ 3.12         | PyQt6              |

💡 Pro Tips

• Use plt.savefig('plot.png') instead of plt.show() if you only need image files
• Test your backend with matplotlib.get_backend() after importing pyplot
• For PyCharm Professional Edition: Enable "Show plots in tool window" in Settings > Tools > Python Scientific
• In Jupyter environments, use %matplotlib inline instead of interactive backends

Conclusion

The "FigureCanvasAgg is non-interactive" warning resolves by switching from the 'Agg' backend to an interactive alternative like TkAgg or QtAgg. The most straightforward solution is simply removing the explicit matplotlib.use('Agg') line. For systems missing GUI dependencies, install platform-appropriate libraries (TkInter/PyQt5 for older Python installs, PyQt6 for newer versions).

Ensure backend selections come before any matplotlib imports in your code. With these adjustments, your plots will display interactively when using plt.show().