Generating Fully Offline Plotly Reports with Inline JavaScript

Problem: Sharing interactive plots without a server or internet connection

You have a Python script that builds Plotly figures and you need to send the results to colleagues who may be working offline, behind strict firewalls, or simply want to open a file in any browser without installing extra software. Relying on a running Python process or an external CDN defeats the purpose of a truly portable report.

Thesis: Using plotly.io.write_html with include_plotlyjs='inline' produces a single, self‑contained HTML file that works offline while preserving Plotly’s interactive features.

Understanding the offline export options

Plotly provides two main ways to embed its JavaScript library when exporting to HTML:

• include_plotlyjs='inline' – the full Plotly.js source (≈2 MB) is copied into the HTML file. The resulting document is completely independent of network access.
• include_plotlyjs='cdn' – only a small placeholder is written; the browser loads Plotly.js from https://cdn.plot.ly at runtime. This keeps the file tiny (< 100 KB) but requires an internet connection.

Both approaches serialize the figure’s data as JSON inside the page, so the chart’s appearance and interactivity (hover, zoom, selection) remain intact as long as the library can be loaded.

Worked example: exporting a simple scatter plot inline

Run the following Python snippet in a terminal or IDE (no special permissions needed; just a standard Python ≥3.8 environment with Plotly installed).

import plotly.graph_objs as go
import plotly.io as pio

# Sample data
x = list(range(1, 101))
y = [v**0.5 for v in x]

fig = go.Figure()
fig.add_trace(go.Scatter(x=x, y=y, mode='lines+markers', name='√x'))
fig.update_layout(title='Square Root Function', xaxis_title='x', yaxis_title='√x')

# Export to a self‑contained HTML file
pio.write_html(
    fig,
    file='sqrt_report.html',
    full_html=True,
    include_plotlyjs='inline',   # <-- key option
    auto_open=False
)
print('File written: sqrt_report.html')

After the script finishes, verify the output:

1. Check file size – run ls -lh sqrt_report.html (Linux/macOS) or dir sqrt_report.html (Windows). You should see a size in the low‑megabyte range (≈2 MB).
2. Confirm offline operation – disconnect your machine from Wi‑Fi/Ethernet, then open sqrt_report.html in Chrome, Firefox, or Safari. Open the browser’s developer tools (F12), select the Network tab, and reload the page. No requests to plotly.com or any CDN domain should appear; all resources are loaded from (disk cache) or (blob).
3. Validate interactivity – hover over points, zoom with the mouse wheel, and use the box‑select tool. The chart should respond exactly as it would in a notebook.

Trade‑offs and limitations

The primary trade‑off is file size versus true offline independence:

• Inline – guarantees zero external requests, but the HTML can be cumbersome for email attachments or low‑bandwidth downloads.
• CDN – yields a lightweight file (< 100 KB) but fails when the viewer lacks internet access or when the CDN is blocked.

For very large datasets (hundreds of thousands of points), the embedded JSON can also bloat the file. In such cases consider:

• Using plotly.graph_objs.Scattergl (WebGL‑based) which reduces the amount of data sent to the browser while still benefiting from offline export.
• Down‑sampling or aggregating data before plotting if exact precision is not required.

Note that offline HTML does not preserve Dash‑specific callbacks or any server‑side interactivity; those features are stripped because there is no Python process to serve them.

Actionable checklist for choosing the right export mode

1. Determine if the recipient will have reliable internet access when opening the report.
2. If yes, and file size matters (e.g., embedding in an email), use include_plotlyjs='cdn'.
3. If no, or you need guaranteed operation in air‑gapped environments, use include_plotlyjs='inline'.
4. For large plots, test both modes: compare file size (ls -lh) and browser performance (open dev tools → Performance tab).
5. After exporting, always verify offline operation by disabling networking and checking the Network tab for external requests.

By following these steps you can generate Plotly reports that are truly portable, interactive, and ready for any environment—online or off.