Diagnosing Invisible or Clipped Matplotlib Plots: A Backend, Size, and Layout Checklist

Recognizable Condition

When you run a Matplotlib script or notebook cell, you see no pop‑up window, the cell returns None, or the figure appears but text and tick labels are cut off or overlap. The code executes without raising an exception, so the problem is purely a rendering issue.

Root Cause & Diagnostic Table

Cause	Typical Symptoms
Backend mismatch	No window opens; plots silently disappear.
Figure size / DPI too small	Entire plot off‑screen or elements clipped.
tight_layout mis‑calculations	Labels overlap, or annotations are cut off.

Ordered Checks

1. Verify the active backend. Run in a terminal or notebook:

   import matplotlib
   print(matplotlib.get_backend())
   

   In a GUI environment you should see TkAgg, Qt5Agg, or similar. If you see Agg or PDF, the backend is non‑interactive.

2. Test a minimal plot. Create a fresh figure and display it:

   import matplotlib.pyplot as plt
   plt.plot([1, 2, 3])
   plt.show()
   

   If this still shows nothing, the problem is with the backend. If a window appears, proceed to the next step.

3. Inspect figure size and DPI. After creating a figure, check:

   fig = plt.figure(figsize=(4, 3), dpi=100)
   print(fig.get_size_inches(), fig.dpi)
   

   A figure of 4×3 inches at 100 dpi renders as 400×300 px. If your window is smaller than this, the content may be drawn off‑screen.

4. Disable tight_layout temporarily. Add plt.tight_layout(False) before plt.show() and observe changes. If the plot appears correctly, the issue lies with layout calculation.
5. Check for conflicting third‑party packages. If you have both PyQt5 and PySide2 installed, Matplotlib may pick the wrong GUI library. Use pip list | grep -E 'PyQt5|PySide2' to inspect.

Fixes Tied to Findings

• Backend mismatch
  Switch to a GUI backend:

  import matplotlib
  matplotlib.use('TkAgg')  # or 'Qt5Agg'
  import matplotlib.pyplot as plt
  

  In Jupyter, enable the inline backend:

  %matplotlib inline
  

  After changing the backend, rerun the minimal plot test.

• Figure size / DPI
  Increase the figure size or reduce DPI:

  fig = plt.figure(figsize=(8, 6), dpi=100)
  

  Alternatively, set a larger default DPI in Matplotlib’s configuration file (matplotlibrc) by adding figure.dpi: 150.

• tight_layout issues
  Adjust padding parameters:

  plt.tight_layout(pad=1.0, w_pad=0.5, h_pad=0.5)
  

  If labels still clash, replace tight_layout with manual adjustments:

  fig.subplots_adjust(left=0.1, right=0.9, top=0.9, bottom=0.1)
  

  For complex grids, consider GridSpec or subplots_adjust directly on each Axes object.

• Conflicting GUI libraries
  Uninstall one of the conflicting packages or pin Matplotlib to a specific backend:

  pip uninstall PySide2
  pip install PyQt5
  

  Then set the backend explicitly as shown above.

Escalation Criteria

1. If no window appears after switching to a GUI backend, verify that the system’s graphics drivers support the chosen toolkit. On Linux, ensure python3-tk is installed; on Windows, the Microsoft Visual C++ Redistributable may be missing.
2. If tight_layout raises an exception like ValueError: All axes must be visible, upgrade Matplotlib:

   pip install --upgrade matplotlib
   

   Newer releases contain bug fixes for layout handling.

3. If annotations are still clipped, move them inside the plot area using bbox_to_anchor or transform=ax.transAxes to keep them within bounds.
4. When all else fails, file an issue on the Matplotlib GitHub tracker with a reproducible snippet and your environment details.

Practical Verification Checklist

• Backend check: print(matplotlib.get_backend()) → should match your display method.
• Figure size: fig.get_size_inches() and fig.dpi → product should be ≥ window size.
• Layout sanity: After tight_layout, run plt.show() and confirm no overlapping text.
• Minimal example success: If a single line plot displays, the environment is functional.

By following this ordered diagnostic path you can isolate whether the problem is a backend mismatch, a sizing issue, or a layout calculation error, and apply the appropriate fix without unnecessary trial and error.