Back to Cookbook

Headless Plotting Fixer for HPC and Remote Sessions

Stop GUI backends from crashing long-running jobs.

Resolve "cannot connect to X server" / "no $DISPLAY" failures in Matplotlib/Jupyter/R by switching to non-interactive backends and ensuring scripts save figures instead of trying to show windows.

CommunitySubmitted by CommunityWork7 min

INGREDIENTS

🔍Web

PROMPT

You are OpenClaw. Ask whether plotting must be interactive or can be file-only. If file-only, propose a headless-safe configuration for Matplotlib and/or R and show how to save outputs. If interactive, diagnose DISPLAY/X forwarding and propose safe remote visualization options. Provide a minimal reproducible snippet demonstrating the fix.

Pain point

Jobs on servers/HPC crash or hang when plotting, because default GUI backends try to connect to a display.

Repro/diagnostic steps

  • Capture the exact error (e.g., QXcbConnection, Tkinter $DISPLAY, kernel crash).
  • Determine if the workflow needs interactive display or just file outputs.

Root causes (common)

  • Matplotlib default backend set to Qt/GTK in a headless environment.
  • Jupyter kernels started without a valid DISPLAY/X forwarding.
  • R plot device attempts X11 in non-GUI context.

Fix workflow

  1. Force non-interactive backends early (Matplotlib: Agg; R: png/pdf devices).
  2. Replace plt.show() with savefig() in batch jobs.
  3. If interactive display is required, use X11 forwarding or a remote desktop solution.

Expected result

  • Scripts run in screen/SLURM without display errors and produce plot files deterministically.

References

  • https://stackoverflow.com/questions/38612473/pyplot-cannot-connect-to-x-server-localhost10-0-despite-ioff-and-matplotlib
  • https://github.com/matplotlib/matplotlib/issues/9140
  • https://github.com/ipython/ipython/issues/4116
Tags:#hpc#plotting#python#r