現場でMatplotlibを使っていると、「UserWarning: Matplotlib is currently using AGG, which is a non-GUI backend...」という警告がコンソールに出ることがある。最初はエラーではないので放置しがちだが、これが原因で意図しない挙動を起こすことがあるため、しっかり向き合う必要があった。

この警告が出たとき、サーバーサイドで動かしているのか、ローカルでインタラクティブな表示を求めているのかで対応が全く変わる。間違った設定のままだと、開発効率やデプロイの安定性に響くので、落ち着いて対処すべきだという話。

何が起きたか（課題）

Matplotlibが警告を発するのは、実行環境がGUIをサポートしていないと判断され、自動的にAGG（Anti-Grain Geometry）バックエンドが選択されたときだ。これによって具体的に発生する主な問題は以下の通りだ。

plt.show() を呼び出してもプロットウィンドウが開かない。
意図せず静的ファイル（PNGなど）として保存されてしまい、ローカルでのデバッグが困難になる。
ログが頻繁に警告で埋まり、本当に重要なエラーが見つけにくくなる。
GUIバックエンド（TkAggなど）を要求する処理が失敗する可能性がある。

どう解決したか（概要）

解決策は、プロットの目的（静的保存か、インタラクティブ表示か）に応じてバックエンドを明示的に指定することに集約される。

サーバーサイドでPNGやPDFを生成する場合：matplotlib.use('Agg') を使用し、警告を抑制しつつ、最も高速な静的生成環境を確立する。この設定は他のmatplotlib関連のインポートよりも前に書く必要がある。
ローカルPCでウィンドウ表示をしたい場合：matplotlib.use('TkAgg') など、GUIをサポートするバックエンドに切り替える。TkAggが最も依存関係が少なく手軽だ。

環境変数 MPLBACKEND を使ってコードを変更せずに制御するアプローチも併用した。

環境と目的に合わせたバックエンド選択の判断基準は以下の通りだ。

用途・環境	推奨バックエンド	特徴と注意点
サーバー、CI/CD (静的画像生成)	Agg	最速。`plt.show()` 不可。
ローカルPC (インタラクティブ表示希望)	TkAgg	Python標準のTkinterに依存。

効果（Before/After）

静的ファイル生成が主目的のサーバー環境で意図的に matplotlib.use('Agg') を設定した結果、ログから不要な警告が完全に消え、デプロイ後のログ監視が非常にクリーンになった。これにより、本当にクリティカルなエラーを見逃すリスクが減った。

また、ローカル環境で plt.show() が動かない問題も、TkAggへの切り替えにより、期待通りにポップアップウィンドウが表示されるようになり、デバッグ体験が劇的に向上した。

🚀 詳細な設定とコードはこちら

具体的なWAFのルール設定や、より詳細なログ解析データは元のブログで公開しています。

👉 MatplotlibのAGGバックエンド警告を解決する方法とは