TclError from TkAgg in headless CI: where should matplotlib's Agg backend be pinned?

Pin Agg in the container environment, not in shared application code

For matplotlib 3.x with a pinned container image and the requirement to keep interactive windows on developer machines, force Agg only in headless CI via the process environment. Set MPLBACKEND=Agg in the Dockerfile or CI job before Python starts. Do not hardcode matplotlib.use('Agg') in library or application modules.

Likely explanation

The container inherits a default or user‑configured interactive backend such as TkAgg. TkAgg requires a windowing system and a functional Tcl/Tk installation. In a headless CI or Docker image without a display, figure rendering triggers a TclError even though the same code works on developer desktops.

Confirmed facts

• matplotlib.use(backend) must run before the first import of matplotlib.pyplot or any module that imports it. After pyplot is imported, a non‑force call warns and does not switch backends.
• MPLBACKEND is read at process start and selects the backend before any import occurs. An explicit matplotlib.use() call in code overrides MPLBACKEND for that process.
• matplotlib.get_backend() reports the effective backend name after imports. It can be used as a runtime assertion in tests, but a passing check only confirms the name, not that rendering will succeed.
• There is no clean supported backend switch after pyplot has been imported. force=True is not a reliable substitute and can leave figure manager state inconsistent.

Steps for this case

1. Set the backend in CI/container only.

   # Dockerfile or CI step
   ENV MPLBACKEND=Agg
   

   This makes every module that imports matplotlib see Agg without changing application code.

2. Keep application code backend‑neutral.

   Do not add a top‑level matplotlib.use('Agg') in shared modules. That would prevent interactive windows on developer machines.

3. Guard tests when needed.

   If a test entry point must guarantee headless rendering, import a small pin module before any pyplot import and assert the backend in CI only.

   import matplotlib
   backend = matplotlib.get_backend().lower()
   assert backend == 'agg', f'Expected Agg, got {backend}'
   

4. Verify.

   python -c \"import matplotlib; print(matplotlib.get_backend())\"
   # expect Agg
   
   python -c \"import matplotlib.pyplot as plt; plt.plot([0,1]); plt.savefig('/tmp/agg_check.png')\"
   # expect exit 0 and non‑empty PNG
   

One diagnostic that changes the recommendation: do any library modules import matplotlib.pyplot at import time rather than lazily inside functions? If yes, import order must be restructured or the environment variable is the only reliable enforcement point.