Plotly · Class

go.Image

go.Image displays multichannel image data as a Plotly graph-object trace. Provide raw pixel values with z or a base64-encoded image through source.

How it works

go.Image is a low-level graph-object trace for displaying multichannel image data. Supply pixel values through z, or use source with a base64-encoded image to reduce browser payload and serialization work.

Syntax

go.Image(z=None, source=None, zmin=None, zmax=None, **kwargs)

Parameters

Name	Type	Description
`z`	`array or list of numerical values`	Image pixel data as an array or list of numerical values; intended for multichannel images.
`source`	`base64 binary string`	A base64-encoded binary image string.
`zmin`	`array-like`	Lower data bound used for color mapping; for `go.Image`, provide one value per channel.
`zmax`	`array-like`	Upper data bound used for color mapping; for `go.Image`, provide one value per channel.

Returns

A Plotly graph-object image trace.

Key points

Use plotly.graph_objects.go.Image when you need direct trace-level control over an image.
Use source for a base64-encoded image payload instead of passing raw pixel arrays.
Compressed image sources can reduce browser transfer size and improve serialization performance.
The lower and upper bounds control how numeric image values map into the displayed range.

Common mistakes

Use go.Heatmap for single-channel images; this trace requires multiple channels.
Do not confuse this trace with go.layout.Image, which is intended for background images and logos.
When setting zmin or zmax, provide values for every channel rather than relying on a single scalar.

Example: Display an RGB image

import plotly.graph_objects as go

img_rgb = [
    [[255, 0, 0], [0, 255, 0], [0, 0, 255]],
    [[0, 255, 0], [0, 0, 255], [255, 0, 0]],
]
fig = go.Figure(go.Image(z=img_rgb))
fig.show()

Creates and displays a Plotly figure from a small RGB pixel array.

When to use it

Display multichannel arrays

Render RGB or RGBA pixel arrays interactively in a Plotly figure.

Reduce browser payload

Send compressed PNG or JPEG data instead of large raw arrays.

Tune image value ranges

Control how channel values map to displayed colors.

Interview questions

QWhat is go.Image used for?

go.Image is a graph-object trace for displaying multichannel image data. A typical figure passes an RGB array to z and then renders the figure.

Follow-up: How would you display a grayscale image? Use go.Heatmap, because go.Image accepts only multichannel images.

QWhat are the main ways to provide image data?

The z property accepts an array or list of numerical values representing image data. The alternative source property accepts a base64 binary string.

Follow-up: Why might source be preferable? PNG or JPEG compression can reduce data sent to the browser and serialization time.

QHow are image values mapped to colors?

zmin and zmax map data values to the image color range. For go.Image, these bounds must be specified for every channel.

Follow-up: How does this differ from px.imshow? px.imshow can accept a scalar bound and reuse it across channels, while go.Image requires channel-wise bounds.

go.Heatmap
go.layout.Image
px.imshow

Source: Imshow. Checked 2026-10-15.