Visualize a numeric matrix as a heatmap.
Numeric matrix exploration
Plotly · Function
px.imshow
Creates a Plotly figure from matrix-like data, rendering scalar values as heatmap pixels or displaying RGB/RGBA image arrays. The result is a customizable interactive figure.
How it works
px.imshow converts matrix-like data into a Plotly figure where values become heatmap pixels. It also accepts image-shaped arrays, including RGB or multidimensional data, and returns a figure that can be further customized before display.
Syntax
plotly.express.imshow(img, zmin=None, zmax=None, origin=None, labels=None, x=None, y=None, animation_frame=None, facet_col=None, facet_col_wrap=None, facet_col_spacing=None, facet_row_spacing=None, color_continuous_scale=None, color_continuous_midpoint=None, range_color=None, title=None, template=None, width=None, height=None, aspect=None, contrast_rescaling=None, binary_string=None, binary_backend="auto", binary_compression_level=4, range_x=None, range_y=None, text_auto=False, aspect=None, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
img | array-like or DataFrame | Input array-like, NumPy, xarray, or supported DataFrame containing matrix or image data. |
x | array-like | Optional x-axis coordinate or label values. |
y | array-like | Optional y-axis coordinate or label values. |
binary_string | bool | Controls whether image data is transferred as a PNG string. |
text_auto | bool or str | Adds automatic value annotations; a d3-format string controls formatting. |
zmin, zmax | number | Lower and upper values used for color mapping. |
labels | dict | Text and axis labeling configuration. |
Returns
A plotly.graph_objects.Figure instance.
Key points
- Each matrix or DataFrame value becomes one heatmap pixel.
- The same function supports scalar heatmaps and full-color images.
- Inputs may be nested lists, NumPy arrays, xarray arrays, or supported DataFrames.
- Two-dimensional scalar input is rendered by mapping values through a colorscale.
- If no colorscale is selected, the active Plotly template supplies the default.
Common mistakes
- Setting
binary_string=Truechanges the image representation sent to the browser; use it deliberately when controlling payload or rendering behavior.
Example: Annotated heatmap
import plotly.express as px
fig = px.imshow([[1, 20, 30], [20, 1, 60], [30, 60, 1]], text_auto=True)
fig.show()Creates an annotated heatmap from a two-dimensional numeric matrix.
When to use it
Render RGB or RGBA array data as an image.
Image display
Show formatted values directly on heatmap cells.
Annotated analysis
Facet or animate multidimensional image data.
Image collections
Interview questions
QWhat does px.imshow represent?
It creates a Plotly figure from matrix-like data, mapping each input value to a heatmap pixel. It can also display full-color images and supports array-like, NumPy, xarray, and supported DataFrame inputs.
Follow-up: How would you label the axes? Supply x, y, and labels, then use figure axis methods such as update_xaxes() for placement.
QHow are scalar values colored and annotated?
For two-dimensional scalar data, it maps values to colors through a colorscale. The default colorscale comes from the active template, while zmin and zmax control the mapped data range.
Follow-up: How can annotations be added? Pass text_auto=True, or provide a d3-format string to control annotation formatting.
QWhat does the function return?
The function returns a plotly.graph_objects.Figure. That figure can be displayed with show() and modified with standard figure methods such as update_layout and add_trace.
Follow-up: What input shape is suitable for an RGB image? Use a three-dimensional array whose final dimension contains the color channels.
Related
plotly.expressplotly.graph_objects.Figureheatmapgo.Imageupdate_xaxestext_auto