# ImportError: Cannot load backend 'TkAgg' which requires the 'tkinter' interactive framework, as 'headless' is not running a display.

- **ID:** `python/matplotlib-agg-backend-missing`
- **Domain:** python
- **Category:** module_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

Running matplotlib on a headless server without a display, but the default backend (TkAgg) requires a graphical environment.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 3.7 | active | — | — |
| 3.8 | active | — | — |

## Workarounds

1. **Set the Agg backend before importing matplotlib.pyplot** (95% success)
   ```
   import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt
   ```
2. **Use the 'pdf' or 'svg' backend for file output** (90% success)
   ```
   import matplotlib; matplotlib.use('PDF'); import matplotlib.pyplot as plt
   ```

## Dead Ends

- **Installing tkinter via pip** — tkinter is part of the standard library and cannot be installed via pip; the issue is the missing display, not the module. (95% fail)
- **Setting backend after importing pyplot** — The backend must be set before importing pyplot; setting it after has no effect. (90% fail)