Plotly — interactive charting

Version: 6.6.0 Type: Pure Python (+ bundled JS renderer assets in package_data/) SPM target: Plotly Auto-includes: (none; pulled in by Dash, matplotlib-shim, seaborn-shim) Total Python modules: 300+ (chart trace classes + figure factories + IO renderers)

Plotly is the rendering engine behind the matplotlib + seaborn shims, and the default chart widget in Dash. Can also be used directly via plotly.graph_objects (low-level trace builder) or plotly.express (one-line declarative high-level API). Renders to interactive HTML in WKWebView on iOS.

Modules

Top-level

Module	What it does
`plotly.__init__`	Re-exports `graph_objects`, `express`, `io`, `subplots.make_subplots`, `colors`, plus version info
`plotly.basedatatypes`	`BaseFigure`, `BaseTraceType`, `BaseLayoutType` (every Figure / trace inherits from these)
`plotly.basewidget`	`BaseFigureWidget` (anywidget-based interactive widget)
`plotly.subplots`	`make_subplots(rows, cols, specs=, shared_xaxes=, ...)`
`plotly._subplots`	Internal subplot grid builder
`plotly.animation`	`Frame`, `Animation` config helpers
`plotly.callbacks`	Hover / click / selection event payload classes (`PlotlyCallbackInput`, `Points`, `InputDeviceState`)
`plotly.colors`	Color palettes (Viridis, Plasma, Inferno, Cividis, plus categorical: Plotly, D3, G10, T10, Alphabet, Dark24, Light24); `n_colors`, `find_intermediate_color`, `sample_colorscale`, `hex_to_rgb`, `label_rgb`
`plotly.data`	Built-in demo datasets: `iris`, `tips`, `gapminder`, `wind`, `election`, `carshare`, `medals_long`, `medals_wide`, `stocks`, `experiment`
`plotly.exceptions`	`PlotlyError`, `PlotlyDictKeyError`, `PlotlyDataTypeError`
`plotly.files`	Config + credential file locations (~/.plotly/...) — unused offline
`plotly.serializers`	Numpy + datetime → JSON serialization with `_plotly_utils.utils.PlotlyJSONEncoder`
`plotly.shapeannotation`	Auto-positioned text labels for shapes (`hline`/`vline`/`hrect`/`vrect`)
`plotly.tools`	Legacy helpers (`make_subplots`, `validate`, `mpl_to_plotly`) — most superseded
`plotly.utils`	`PlotlyJSONEncoder`, color utils, validator dispatch
`plotly.optional_imports`	Lazy-import helper used everywhere
`plotly.validator_cache` / `plotly.validators`	1500+ per-attribute validator classes — autogenerated, loaded lazily
`plotly.conftest`	pytest fixtures (test-only)
`plotly.missing_anywidget`	Stub shown if `anywidget` isn't installed (it isn't, on iOS — interactive `FigureWidget` is therefore degraded)
`plotly.labextension` / `plotly.package_data`	JS renderer + JupyterLab extension assets bundled with the wheel

`plotly.graph_objects` — explicit trace builder

plotly.graph_objects re-exports from plotly.graph_objs (the auto-generated module). 107 files, one per trace / layout / frame class. Selected:

Basic charts: go.Scatter, go.Bar, go.Pie, go.Histogram, go.Histogram2d, go.Histogram2dContour, go.Box, go.Violin, go.Heatmap, go.Contour, go.Table

Statistical: go.Splom, go.Parcoords, go.Parcats, go.Indicator, go.Scatterternary

3D: go.Scatter3d, go.Surface, go.Mesh3d, go.Isosurface, go.Volume, go.Cone, go.Streamtube

Polar / specialized: go.Scatterpolar, go.Barpolar, go.Scattersmith

Geographic: go.Scattergeo, go.Choropleth, go.Scattermap, go.Choroplethmap, go.Densitymap, go.Scattermapbox, go.Choroplethmapbox, go.Densitymapbox

Financial / hierarchical: go.Candlestick, go.Ohlc, go.Funnel, go.Funnelarea, go.Waterfall, go.Treemap, go.Sunburst, go.Icicle, go.Sankey

Carpet / image: go.Carpet, go.Scattercarpet, go.Contourcarpet, go.Image

Containers: go.Figure, go.FigureWidget, go.Layout, go.Frame

Every trace has corresponding sub-modules for nested attributes (e.g. go.scatter.marker.Line, go.layout.xaxis.RangeSelector). These live in plotly.graph_objs.<trace>.* and are auto-loaded.

`plotly.express` — high-level one-liner API

Available on iOS (the existing docs noted it as missing — that's outdated; it ships).

Submodule	What it does
`express.__init__`	Re-exports all `px.*` chart functions
`express._chart_types`	`scatter`, `line`, `area`, `bar`, `histogram`, `violin`, `box`, `strip`, `ecdf`, `density_heatmap`, `density_contour`, `pie`, `sunburst`, `treemap`, `icicle`, `funnel`, `funnel_area`, `scatter_3d`, `line_3d`, `scatter_polar`, `line_polar`, `bar_polar`, `scatter_ternary`, `line_ternary`, `scatter_mapbox`, `line_mapbox`, `choropleth_mapbox`, `density_mapbox`, `scatter_geo`, `line_geo`, `choropleth`, `parallel_coordinates`, `parallel_categories`, `imshow`, `scatter_matrix`, `timeline`
`express._core`	Trace-building engine
`express._imshow` / `imshow_utils`	`px.imshow` for arrays/images
`express._special_inputs`	`IdentityMap`, `Constant`, `Range` for axis input
`express._doc`	Docstring scaffolding
`express.colors` / `express.data`	Re-exports of `plotly.colors` / `plotly.data`
`express.trendline_functions`	`ols`, `lowess`, `rolling`, `ewm`, `expanding` (needs pandas/statsmodels)

Note: plotly.express typically expects pandas DataFrames as input, but accepts dicts and array-like inputs too. Plain-Python iterables work for most charts.

`plotly.io` — figure I/O and renderers

Submodule	What it does
`io.__init__`	Re-exports `show`, `to_html`, `from_json`, `to_json`, `read_json`, `write_json`, `templates`, `renderers`
`io._html`	`to_html`, `write_html` — produces a standalone HTML doc embedding `plotly.js`
`io._json` / `io.json`	JSON figure (de)serialization
`io._renderers` / `io.base_renderers`	`renderers["browser"]`, `renderers["iframe"]`, `renderers["png"]`, `renderers["jpeg"]`, `renderers["svg"]`, `renderers["pdf"]`, `renderers["notebook"]`, `renderers["vscode"]`, …
`io._templates`	Built-in templates: `plotly`, `plotly_white`, `plotly_dark`, `ggplot2`, `seaborn`, `simple_white`, `presentation`, `xgridoff`, `ygridoff`, `gridon`, `none`
`io._defaults`	`plotly.io.defaults.default_format`, `default_width`, etc.
`io._kaleido` / `io.kaleido`	Image export via Kaleido (Chromium-based renderer) — iOS-unavailable (no Chromium / no subprocess)
`io._orca` / `io.orca`	Legacy image export via Orca (deprecated, subprocess-based) — iOS-unavailable
`io._sg_scraper`	Sphinx Gallery integration (docs builds)
`io._utils`	Misc helpers
`io._base_renderers`	Base classes for custom renderers

`plotly.figure_factory` — pre-built composite charts

Module	What it does
`_distplot`	`create_distplot` (multi-rug + KDE + histogram) — needs scipy
`_2d_density`	`create_2d_density`
`_annotated_heatmap`	`create_annotated_heatmap`
`_bullet`	`create_bullet`
`_candlestick` / `_ohlc`	`create_candlestick`, `create_ohlc`
`_county_choropleth`	`create_choropleth` — US-counties choropleth
`_dendrogram`	`create_dendrogram` — hierarchical clustering (scipy)
`_facet_grid`	`create_facetgrid`
`_gantt`	`create_gantt`
`_hexbin_map`	`create_hexbin_mapbox`
`_quiver` / `_streamline`	Vector field plots
`_scatterplot`	`create_scatterplotmatrix`
`_table`	`create_table` (DataFrame → table)
`_ternary_contour`	`create_ternary_contour`
`_trisurf`	`create_trisurf`
`_violin`	`create_violin`

`plotly.matplotlylib` — matplotlib → plotly converter

Module	What it does
`matplotlylib.__init__`	`mpl_to_plotly(fig)` — convert a matplotlib `Figure` to plotly
`matplotlylib.mpltools`	mpl → plotly attribute mapping
`matplotlylib.renderer`	The visitor that walks the mpl artist tree
`matplotlylib.mplexporter`	Vendored matplotlib exporter

The iOS matplotlib shim uses this internally to render mpl figures via plotly's renderer.

`plotly.offline`

Module	What it does
`offline.__init__`	Legacy offline mode: `plot()`, `iplot()`, `init_notebook_mode()` — superseded by `plotly.io` but still works

`plotly.api` — REST client (Chart Studio)

Empty on iOS — Chart Studio (chart_studio.plotly) isn't bundled because it needs network credentials and serves no offline use case.

`_plotly_utils` (sibling package, not under `plotly/`)

Helpers shared between plotly and the (unbundled) plotly-orca:

_plotly_utils.basevalidators (validator base classes), _plotly_utils.colors (color-conversion helpers), _plotly_utils.utils (JSON encoder), _plotly_utils.png (PNG decoder), _plotly_utils.optional_imports, _plotly_utils.data_utils, _plotly_utils.exceptions, _plotly_utils.importers, _plotly_utils.files.

iOS-specific notes

Charts render as interactive HTML in WKWebView — hover tooltips, zoom/pan, box/lasso selection, legend toggle, axis range slider, screenshot export all work.
Image export via Kaleido / Orca: NOT available — both need an embedded Chromium browser + subprocess control. On iOS use to_html() instead, or take a screenshot of the rendered chart.
FigureWidget — degraded; anywidget isn't bundled. Use go.Figure().show() which renders via the static HTML renderer.
plotly.express — works (the older docs noted it as missing; that's outdated). Pandas is bundled in this distribution, so the typical DataFrame input path is fine.
Mapbox / Mapboxgl traces — render but need a Mapbox token for the styled tiles. The default open-street-map style works without a token.
plotly.io.templates.default = "plotly_dark" — useful in WKWebView's default dark-mode rendering; otherwise dark-mode users get a white chart on a dark page.

Standalone example

import plotly.graph_objects as go

fig = go.Figure()
fig.add_trace(go.Scatter(x=[1, 2, 3, 4], y=[10, 11, 12, 13],
                         mode="lines+markers", name="Series A"))
fig.add_trace(go.Bar(x=[1, 2, 3, 4], y=[5, 4, 3, 6], name="Series B"))
fig.update_layout(
    title="Mixed Chart",
    xaxis_title="X", yaxis_title="Y",
    template="plotly_white",
    hovermode="x unified",
)
fig.show()                              # renders in WKWebView

# Subplots
from plotly.subplots import make_subplots

fig = make_subplots(
    rows=2, cols=2,
    subplot_titles=["A", "B", "C", "D"],
    specs=[[{"type": "scatter"}, {"type": "bar"}],
           [{"type": "pie"},     {"type": "heatmap"}]],
)
fig.add_trace(go.Scatter(x=[1,2,3], y=[4,5,6]), row=1, col=1)
fig.add_trace(go.Bar(x=[1,2,3],     y=[2,3,1]), row=1, col=2)
fig.show()

# plotly.express one-liner
import plotly.express as px
import pandas as pd

df = pd.DataFrame({"x": range(50), "y": [i*i for i in range(50)]})
px.line(df, x="x", y="y", title="y = x²").show()

Layout configuration

fig.update_layout(
    title=dict(text="Title", x=0.5, font=dict(size=20)),
    xaxis=dict(title="X", range=[0, 10], type="linear", showgrid=True,
               gridcolor="lightgray"),
    yaxis=dict(title="Y", type="log", zeroline=True),
    legend=dict(x=0, y=1, bgcolor="rgba(255,255,255,0.5)"),
    template="plotly_white",            # or plotly, plotly_dark, ggplot2, seaborn, simple_white
    font=dict(family="Arial", size=12, color="black"),
    width=800, height=600,
    margin=dict(l=60, r=30, t=60, b=60),
    showlegend=True,
    hovermode="closest",                # or x, y, x unified, y unified
    plot_bgcolor="white",
    paper_bgcolor="white",
)

Annotations and shapes

fig.add_annotation(x=2, y=5, text="Peak", showarrow=True, arrowhead=2)
fig.add_shape(type="rect", x0=1, y0=1, x1=3, y1=5, line=dict(color="red"))
fig.add_shape(type="circle", x0=0, y0=0, x1=2, y1=2,
              fillcolor="lightblue", opacity=0.3)
fig.add_hline(y=3, line_dash="dot", line_color="green")
fig.add_vline(x=2, line_dash="dash")
fig.add_hrect(y0=1, y1=3, fillcolor="yellow", opacity=0.2)
fig.add_vrect(x0=0, x1=2, fillcolor="red", opacity=0.1)

Limitations

Image export (PNG/JPEG/SVG/PDF) via Kaleido / Orca — both need Chromium subprocesses and aren't available on iOS. Workaround: to_html() + browser screenshot, or render via Dash and screenshot the WebView
Chart Studio cloud sync (plotly.api, chart_studio) — not bundled
FigureWidget interactivity — degraded without anywidget; use static Figure().show() instead
Dash itself — bundled separately as the Dash SPM target; see dash.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Plotly — interactive charting

Modules

Top-level

`plotly.graph_objects` — explicit trace builder

`plotly.express` — high-level one-liner API

`plotly.io` — figure I/O and renderers

`plotly.figure_factory` — pre-built composite charts

`plotly.matplotlylib` — matplotlib → plotly converter

`plotly.offline`

`plotly.api` — REST client (Chart Studio)

`_plotly_utils` (sibling package, not under `plotly/`)

iOS-specific notes

Standalone example

Layout configuration

Annotations and shapes

Limitations

See also

FilesExpand file tree

plotly.md

Latest commit

History

plotly.md

File metadata and controls

Plotly — interactive charting

Modules

Top-level

plotly.graph_objects — explicit trace builder

plotly.express — high-level one-liner API

plotly.io — figure I/O and renderers

plotly.figure_factory — pre-built composite charts

plotly.matplotlylib — matplotlib → plotly converter

plotly.offline

plotly.api — REST client (Chart Studio)

_plotly_utils (sibling package, not under plotly/)

iOS-specific notes

Standalone example

Layout configuration

Annotations and shapes

Limitations

See also

`plotly.graph_objects` — explicit trace builder

`plotly.express` — high-level one-liner API

`plotly.io` — figure I/O and renderers

`plotly.figure_factory` — pre-built composite charts

`plotly.matplotlylib` — matplotlib → plotly converter

`plotly.offline`

`plotly.api` — REST client (Chart Studio)

`_plotly_utils` (sibling package, not under `plotly/`)