Creating Self‑Contained Interactive Plots with Plotly’s Offline Mode

Problem: Sharing Interactive Plots Without a Server

When you need to distribute a data‑driven report, embedding a live Plotly chart often means requiring a web server or an internet connection to load the Plotly.js library. In environments where only static files can be shared — such as email attachments, internal wikis, or archival storage — this dependency becomes a barrier. Plotly’s offline plotting feature solves this by bundling the library directly into the HTML file, producing a fully interactive, self‑contained visualization that opens in any modern browser.

How Plotly’s Offline API Works

The plotly.offline submodule provides two main functions:

• plot(fig, filename, auto_open=False, include_plotlyjs='embed') writes a standalone HTML file.
• iplot(fig) (Jupyter‑specific) displays the plot inline while still using the same offline machinery.

The key argument is include_plotlyjs:

'embed'Serializes the full Plotly.js library into a <script> block inside the HTML. The resulting file is larger but works completely offline. 'cdn'Inserts a <script src="https://cdn.plot.ly/plotly-latest.min.js"> tag. The HTML stays small, but the viewer must reach the CDN.

All interactivity — hover tooltips, zoom, pan, legend toggles — is preserved because the bundled library contains the same rendering engine used in online mode.

Worked Example: Scatter Plot to Standalone HTML

The following Python snippet creates a simple scatter plot using Plotly Express and saves it as an offline HTML file.

import plotly.express as px
import plotly.offline as po

# Sample data
fig = px.scatter(
    x=[1, 2, 3, 4, 5],
    y=[2, 5, 3, 8, 7],
    title='Sample Scatter Plot',
    labels={'x': 'X axis', 'y': 'Y axis'}
)

# Generate offline HTML with the library embedded
po.plot(
    fig,
    filename='scatter_offline.html',
    auto_open=False,          # Set True to open automatically after creation
    include_plotlyjs='embed'  # Use 'cdn' for a smaller file that needs internet
)

After running the script, open scatter_offline.html in a browser. You should see the scatter plot with hover tooltips showing the exact (x, y) values, and you can zoom or pan using the mouse. Inspecting the file’s source reveals a large <script> block near the top that contains the entire Plotly.js library — this is what makes the file self‑contained.

Trade‑offs and Limitations

• File size: Embedding the library adds roughly 2–3 MB to the HTML. For plots with thousands of data points, the serialized JSON of the data can increase the size further. In such cases, consider downsampling or using include_plotlyjs='cdn' if the audience can reach the internet.
• Version compatibility: The API shown here is stable from Plotly 4.0 onward. Older releases (≤1.5) placed the offline functions under different names and required slightly different arguments. Verify your installed version with import plotly; print(plotly.__version__).
• No server‑side features: Offline HTML cannot execute callbacks that require a Python backend (e.g., Dash‑style interactivity). It is limited to the built‑in Plotly.js UI interactions.

Actionable Checklist

1. Install Plotly: pip install plotly (or npm install plotly.js-dist for JavaScript).
2. Create your Figure using Plotly Express, Graph Objects, or any other method.
3. Call plotly.offline.plot with include_plotlyjs='embed' for true offline use, or 'cdn' if file size is a concern and internet access is guaranteed.
4. Open the generated HTML in a browser to confirm interactivity (hover, zoom, legend).
5. Check the file size; if it exceeds your sharing limits, try reducing data points or switching to the CDN option.
6. When distributing, include a brief note that the file requires a modern browser (Chrome, Firefox, Safari, Edge) and that no additional software is needed.