Change the Colorbar Title in Plotly Express Density Heatmaps and 2D Histograms

Learn how to change the colorbar title in Plotly Express density heatmaps and 2D histograms using update_layout and coloraxis_colorbar, not legend settings.

When you render a density heatmap or a 2D histogram in Plotly Express, the aggregation result is displayed on the colorbar with a default title like “count.” Sometimes this wording isn’t what you want to show users. The goal is simple: change that displayed label without altering the underlying aggregation.

Reproducing the issue

The baseline example mirrors the common quick-start flow and shows the default “count” label on the colorbar. The code below creates the figure using the built-in sample dataset.

import plotly.express as px
tips_source = px.data.tips()
heatmap_fig = px.density_heatmap(tips_source, x="total_bill", y="tip")
heatmap_fig.show()

Attempting to use a classic legend control like update_layout(legend_title_text="...") will not change the colorbar title here.

Why this happens

In this chart type, the label you see next to the colorscale is not a categorical legend—it’s a colorbar tied to the underlying color axis. Therefore, properties that target the legend won’t apply to it. The correct place to update the displayed text is the colorbar title under the color axis configuration in the figure layout.

The fix

Set the title of the colorbar via the coloraxis_colorbar path. The following example updates the colorbar title explicitly.

import plotly.express as px
sample_frame = px.data.tips()
heatmap_obj = px.density_heatmap(sample_frame, x="total_bill", y="tip")
heatmap_obj.update_layout(coloraxis_colorbar=dict(
    title=dict(text="Number of Bills per Cell")
))
heatmap_obj.show()

If you prefer a shorter syntax, you can set the same value in one line using coloraxis_colorbar_title_text.

import plotly.express as px
src = px.data.tips()
hm = px.density_heatmap(src, x="total_bill", y="tip")
hm.update_layout(coloraxis_colorbar_title_text="Number of Bills per Cell")
hm.show()

Why it matters

The right label improves readability and makes the intent of your visualization obvious. When stakeholders scan a dashboard, they rely on concise, accurate annotations. Renaming the colorbar title clarifies that the colors encode aggregated counts per bin rather than a category label, reducing misinterpretation.

Conclusion

For density heatmaps and 2D histograms in Plotly Express, change the displayed aggregation label by targeting the colorbar title, not the legend. Use update_layout with either coloraxis_colorbar.title.text or the concise coloraxis_colorbar_title_text. This small tweak keeps the data logic intact while making your visualizations easier to read and explain in any technical context.