Plotly
Python graphing library for creating interactive, publication-quality visualizations with 40+ chart types.
Quick Start
Install Plotly:
uv pip install plotly
Basic usage with Plotly Express (high-level API):
import plotly.express as px
import pandas as pd
df = pd.DataFrame({
'x': [1, 2, 3, 4],
'y': [10, 11, 12, 13]
})
fig = px.scatter(df, x='x', y='y', title='My First Plot')
fig.show()
Choosing Between APIs
Use Plotly Express (px)
For quick, standard visualizations with sensible defaults:
- Working with pandas DataFrames
- Creating common chart types (scatter, line, bar, histogram, etc.)
- Need automatic color encoding and legends
- Want minimal code (1-5 lines)
See reference/plotly-express.md for complete guide.
Use Graph Objects (go)
For fine-grained control and custom visualizations:
- Chart types not in Plotly Express (3D mesh, isosurface, complex financial charts)
- Building complex multi-trace figures from scratch
- Need precise control over individual components
- Creating specialized visualizations with custom shapes and annotations
See reference/graph-objects.md for complete guide.
Note: Plotly Express returns graph objects Figure, so you can combine approaches:
fig = px.scatter(df, x='x', y='y')
fig.update_layout(title='Custom Title') # Use go methods on px figure
fig.add_hline(y=10) # Add shapes
Core Capabilities
1. Chart Types
Plotly supports 40+ chart types organized into categories:
Basic Charts: scatter, line, bar, pie, area, bubble
Statistical Charts: histogram, box plot, violin, distribution, error bars
Scientific Charts: heatmap, contour, ternary, image display
Financial Charts: candlestick, OHLC, waterfall, funnel, time series
Maps: scatter maps, choropleth, density maps (geographic visualization)
3D Charts: scatter3d, surface, mesh, cone, volume
Specialized: sunburst, treemap, sankey, parallel coordinates, gauge
For detailed examples and usage of all chart types, see reference/chart-types.md.
2. Layouts and Styling
Subplots: Create multi-plot figures with shared axes:
from plotly.subplots import make_subplots
import plotly.graph_objects as go
fig = make_subplots(rows=2, cols=2, subplot_titles=('A', 'B', 'C', 'D'))
fig.add_trace(go.Scatter(x=[1, 2], y=[3, 4]), row=1, col=1)
Templates: Apply coordinated styling:
fig = px.scatter(df, x='x', y='y', template='plotly_dark')
# Built-in: plotly_white, plotly_dark, ggplot2, seaborn, simple_white
Customization: Control every aspect of appearance:
- Colors (discrete sequences, continuous scales)
- Fonts and text
- Axes (ranges, ticks, grids)
- Legends
- Margins and sizing
- Annotations and shapes
For complete layout and styling options, see reference/layouts-styling.md.
3. Interactivity
Built-in interactive features:
- Hover tooltips with customizable data
- Pan and zoom
- Legend toggling
- Box/lasso selection
- Rangesliders for time series
- Buttons and dropdowns
- Animations
# Custom hover template
fig.update_traces(
hovertemplate='<b>%{x}</b><br>Value: %{y:.2f}<extra></extra>'
)
# Add rangeslider
fig.update_xaxes(rangeslider_visible=True)
# Animations
fig = px.scatter(df, x='x', y='y', animation_frame='year')
For complete interactivity guide, see reference/export-interactivity.md.
4. Export Options
Interactive HTML:
fig.write_html('chart.html') # Full standalone
fig.write_html('chart.html', include_plotlyjs='cdn') # Smaller file
Static Images (requires kaleido):
uv pip install kaleido
fig.write_image('chart.png') # PNG
fig.write_image('chart.pdf') # PDF
fig.write_image('chart.svg') # SVG
For complete export options, see reference/export-interactivity.md.
Common Workflows
Scientific Data Visualization
import plotly.express as px
# Scatter plot with trendline
fig = px.scatter(df, x='temperature', y='yield', trendline='ols')
# Heatmap from matrix
fig = px.imshow(correlation_matrix, text_auto=True, color_continuous_scale='RdBu')
# 3D surface plot
import plotly.graph_objects as go
fig = go.Figure(data=[go.Surface(z=z_data, x=x_data, y=y_data)])
Statistical Analysis
# Distribution comparison
fig = px.histogram(df, x='values', color='group', marginal='box', nbins=30)
# Box plot with all points
fig = px.box(df, x='category', y='value', points='all')
# Violin plot
fig = px.violin(df, x='group', y='measurement', box=True)
Time Series and Financial
# Time series with rangeslider
fig = px.line(df, x='date', y='price')
fig.update_xaxes(rangeslider_visible=True)
# Candlestick chart
import plotly.graph_objects as go
fig = go.Figure(data=[go.Candlestick(
x=df['date'],
open=df['open'],
high=df['high'],
low=df['low'],
close=df['close']
)])
Multi-Plot Dashboards
from plotly.subplots import make_subplots
import plotly.graph_objects as go
fig = make_subplots(
rows=2, cols=2,
subplot_titles=('Scatter', 'Bar', 'Histogram', 'Box'),
specs=[[{'type': 'scatter'}, {'type': 'bar'}],
[{'type': 'histogram'}, {'type': 'box'}]]
)
fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6]), row=1, col=1)
fig.add_trace(go.Bar(x=['A', 'B'], y=[1, 2]), row=1, col=2)
fig.add_trace(go.Histogram(x=data), row=2, col=1)
fig.add_trace(go.Box(y=data), row=2, col=2)
fig.update_layout(height=800, showlegend=False)
Integration with Dash
For interactive web applications, use Dash (Plotly's web app framework):
uv pip install dash
import dash
from dash import dcc, html
import plotly.express as px
app = dash.Dash(__name__)
fig = px.scatter(df, x='x', y='y')
app.layout = html.Div([
html.H1('Dashboard'),
dcc.Graph(figure=fig)
])
app.run_server(debug=True)
Reference Files
- plotly-express.md - High-level API for quick visualizations
- graph-objects.md - Low-level API for fine-grained control
- chart-types.md - Complete catalog of 40+ chart types with examples
- layouts-styling.md - Subplots, templates, colors, customization
- export-interactivity.md - Export options and interactive features
Additional Resources
- Official documentation: https://plotly.com/python/
- API reference: https://plotly.com/python-api-reference/
- Community forum: https://community.plotly.com/