Plotly · Class

go.Contour

go.Contour creates an interactive 2D contour plot from a numerical z array. Optional one-dimensional x and y arrays specify the horizontal and vertical coordinates.

How it works

go.Contour is a graph-object trace for visualizing interpolated isovalue lines from a two-dimensional numeric z array. Supply one-dimensional x and y coordinate arrays when the grid axes need explicit values, then place the trace in a figure and display it.

Syntax

go.Contour(z=z, x=x, y=y, contours_coloring="lines", showscale=False)

Parameters

Name	Type	Description
`z`	`array-like`	Two-dimensional numerical array whose values determine the contour levels.
`x`	`array-like`	One-dimensional values for the horizontal axis.
`y`	`array-like`	One-dimensional values for the vertical axis.
`contours_coloring`	`string`	Controls how contours are colored, such as with lines or a heatmap.
`showscale`	`boolean`	Controls whether the color scale is displayed.

Returns

A Plotly graph-object contour trace, intended to be supplied as figure data.

Key points

The trace visualizes equal-value contours calculated from a two-dimensional numerical z array.
The x coordinate array defines positions along the horizontal axis.
The y coordinate array defines positions along the vertical axis.
Set contours_coloring to "lines" when the visualization should emphasize contour boundaries without heatmap-style filling.
A contour trace can be inserted into a particular subplot cell, and its color scale can be hidden with showscale=False.

Common mistakes

The primary data must be a two-dimensional numerical z array; the trace represents interpolated isovalue lines rather than arbitrary point data.
When coordinates are supplied, use one-dimensional x and y arrays describing the horizontal and vertical axes.

Example: Basic contour trace

import plotly.graph_objects as go

fig = go.Figure(go.Contour(
    z=[[10, 10.625, 12.5], [5.625, 6.25, 8.125], [2.5, 3.125, 5.0]],
    x=[-9, -6, -5],
    y=[0, 1, 4],
    contours_coloring="lines"
))
fig.show()

Creates and displays a contour trace from a two-dimensional numeric array, with optional one-dimensional coordinates and line-only coloring.

When to use it

Isovalue mapping

Visualize a scalar field sampled on a rectangular grid.

Heatmap-style contouring

Display a filled representation of numerical intensity across two dimensions.

Multi-panel or layered analysis

Overlay contour information on a subplot or another trace.

Interview questions

QWhat data does a contour trace require, and what do x and y represent?

go.Contour renders contour lines derived from a two-dimensional numerical z array. It can also accept one-dimensional x and y arrays to define the horizontal and vertical coordinates.

Follow-up: How would you show only isolines instead of a filled contour map? Set contours_coloring to "lines".

QHow do you create and display a basic Plotly contour chart?

Create the trace with go.Contour, pass it to go.Figure, and call fig.show() to render the interactive chart. The trace can be configured for line-only coloring or other contour presentations.

Follow-up: How can multiple contour representations be composed? Add multiple contour traces to the same figure, configuring each trace independently.

QWhat does interpolation mean in the context of this trace?

A contour plot uses interpolated lines of equal values from the two-dimensional z array. Explicit x and y coordinates let the trace map those values onto specified horizontal and vertical axes.

Follow-up: What should be checked when coordinates do not align with the grid? Verify that the coordinate arrays are one-dimensional and correspond to the dimensions of z.

go.Heatmap
plotly.graph_objects.Figure
contour plots

Source: Contour plots in Python. Checked 2026-10-15.