Plotly Figure.show() output limits in headless CI environments

Direct answer

Plotly does not provide a configuration flag that forces Figure.show() to raise an exception when no renderer is available. There are also no documented environment variables—such as PLOTLY_* or DISPLAY—that explicitly toggle between headless and browser modes. Renderer selection is performed in Python by detecting an IPython/Jupyter kernel and checking which renderer backends are installed.

Confirmed behavior vs. likely explanation

Confirmed: In a plain Python process without IPython, plotly.io.renderers typically leaves no active renderer, and fig.show() completes without raising. It may emit a warning or attempt a browser fallback that silently does nothing in a container.

Likely: The silent no-op is a consequence of renderer-specific fallback logic rather than a deliberate headless switch. Because the API is designed to degrade gracefully, error behavior depends on the selected renderer, not on a global fail-fast setting.

CI-safe pattern

For automated validation, do not rely on show(). Use explicit static export instead:

1. Install Kaleido and pin both plotly and kaleido to versions you have tested. Kaleido bundles or downloads a Chromium binary; CI images may need additional system libraries, so verify the first run in a clean container.
2. Call fig.write_image("figure.png") (or .svg, .pdf, etc.) and assert the file exists and the process exit code is zero.
3. If your pipeline must call show(), set the renderer explicitly beforehand and guard the call:

import plotly.io as pio

pio.renderers.default = "kaleido"

ALLOWED = {"kaleido"}
if pio.renderers.default not in ALLOWED:
    raise RuntimeError(f"Unexpected renderer: {pio.renderers.default}")

fig.show()  # or fig.write_image(...)

Verification

To confirm what Plotly selected in your CI environment, run:

python -c "import plotly.io as pio; print(pio.renderers.default, pio.renderers.active)"

Then run a minimal export to prove headless operation:

python -c "
import plotly.graph_objects as go
fig = go.Figure(data=[go.Scatter(y=[1,3,2])])
fig.write_image('test.png')
"
ls -l test.png

If test.png is created and the exit code is 0, Kaleido is functioning without a display server. If it fails, inspect the Kaleido/Chromium error rather than the show() path.

Version assumptions

Renderer auto-selection and show() fallback behavior are version-sensitive across Plotly 5.x releases. Pin your dependencies and re-verify after upgrades.