Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
ComplexHeatmap is an R package, distributed through Bioconductor, for drawing heatmaps and combining them with annotations and other heatmaps. This page is for researchers and analysts who need to install it, draw a first annotated heatmap from a numeric matrix, and read the result. Facts below were checked against the Bioconductor package page and the package author’s reference book on 2026-11-08; the version shown on Bioconductor was 2.28.0 (Bioconductor release 3.23) at that time, so check the package page for the current release.
Ask CASRAI · free to tryQuestion about this guide? Ask CASRAI answers with linked sources. 2 free questions a day, no account.
What ComplexHeatmap is used for in research
The Bioconductor description reads: “An R package for building complex heatmaps. Arrange multiple heatmaps together and add various annotation graphics” to reveal associations across data sources. In practice that means one numeric matrix (for example genes by samples) drawn as a clustered colour grid, with extra panels attached to its sides: sample-group colour bars, bar plots, point plots, or a second heatmap sharing the same rows. The package is written by Zuguang Gu, is MIT-licensed, and requires R 4.0.0 or later.
Searches for “complexheatmap r” are looking for exactly this: the R package. The Bioconductor page documents an R package only, so Python users are pointed to the alternatives table below.
Install or access
Install from Bioconductor, not from CRAN. The Bioconductor page gives this command:
if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install("ComplexHeatmap")
The release page states the R version that release is built for (R 4.6 for release 3.23 when checked); an older R needs the matching older Bioconductor release. Dependencies installed automatically include circlize (version 0.4.14 or later), GetoptLong, colorspace, clue, RColorBrewer and GlobalOptions. The vignette is available from R with browseVignettes("ComplexHeatmap"), and the full documentation is the author’s ComplexHeatmap Complete Reference. If the heatmap is part of a larger analysis, record the package version in your session information; see computational reproducibility.
Step-by-step: an annotated heatmap from a matrix
The steps below use a simulated matrix so they run anywhere; replace it with your own numeric matrix. The function names and arguments (Heatmap(), name, col, colorRamp2(), top_annotation, HeatmapAnnotation(), column_split, draw()) are those in the package reference book.
- Load the package and build a numeric matrix.
Heatmap()takes a matrix, not a data frame; convert withas.matrix()if needed.library(ComplexHeatmap) library(circlize) set.seed(1) mat = matrix(rnorm(20 * 12), nrow = 20, dimnames = list(paste0("gene", 1:20), paste0("s", 1:12))) - Scale if your question needs it. The reference chapter on a single heatmap does not describe a scaling argument, so scale the matrix yourself before drawing. A common choice (general R practice, not a ComplexHeatmap feature) is row-wise z-scores. Base R’s
scale()works on columns, so transpose, scale, and transpose back:mat_z = t(scale(t(mat))) - Fix the colour mapping with
colorRamp2(). The reference book says to usecirclize::colorRamp2()for continuous colours, because the mapping then follows the breaks you give and is not affected by outliers:col_fun = colorRamp2(c(-2, 0, 2), c("green", "white", "red")) - Add a column annotation.
HeatmapAnnotation()builds the annotation; pass it astop_annotation. A data frame goes in throughdf, and colours through a namedcollist:group = rep(c("control", "treated"), each = 6) ha = HeatmapAnnotation(df = data.frame(group = group), col = list(group = c("control" = "grey60", "treated" = "orange"))) - Create the heatmap.
namesets the legend title and identifies the heatmap;column_splitcuts the columns into slices:ht = Heatmap(mat_z, name = "z-score", col = col_fun, top_annotation = ha, column_split = group, column_title = "Simulated expression") - Draw it.
Heatmap()is only a constructor: clustering and rendering happen at draw time. At the top level of an interactive session the heatmap prints automatically, but inside a function, a loop or an Rscript you must calldraw()explicitly:draw(ht) - Save to a file. Open a graphics device, draw, then close the device (the reference book’s own example uses
pdf()):pdf("heatmap.pdf", width = 8, height = 8) draw(ht) dev.off()
Other arguments documented in the same chapters: cluster_rows = FALSE turns off row clustering, show_row_names = FALSE hides row labels, row_split and row_km/column_km split by a vector or by k-means, clustering_method_rows accepts any method supported by hclust(), and clustering_distance_rows accepts the methods of dist() plus “pearson”, “spearman” and “kendall”. Row annotations use rowAnnotation() (equivalent to HeatmapAnnotation(..., which = "row")) passed as right_annotation or left_annotation. Heatmaps are joined horizontally with + and vertically with %v%. For preparing the input table beforehand, see data frames in R.
Output and how to read it
- Colour legend. The legend title is the heatmap’s
name. WithcolorRamp2(c(-2, 0, 2), ...), values at or beyond the end breaks take the end colours, so a very large value looks the same as 2. If you leavecolunset, the default mapping is data-driven: for mostly positive or mostly negative matrices with more than 100 values it uses the 1st and 99th percentiles, and for centred data the 99th percentile of the absolute values (reference book). Two heatmaps made with different defaults are therefore not directly comparable by colour. - Dendrograms and order. Rows and columns are reordered by hierarchical clustering unless you switch it off, so neighbouring rows are similar under the chosen distance and linkage. Read the dendrogram heights for how different clusters are.
- Splits. With
column_split, the gaps between slices mark the groups you defined, not data-driven clusters. Withrow_km/column_km, slices come from k-means. - Annotations. Colour bars are your labels, drawn alongside the data. Samples of one group sitting together after clustering is a visual observation; follow it with a statistical test rather than reporting the picture as the result.
Troubleshooting
The heatmap does not appear when run in a function, loop or script
Call draw(ht). The reference book states that Heatmap() is only a constructor, so nothing is drawn until the object is drawn explicitly outside top-level interactive use.
Error about the input not being a matrix
The first argument must be a matrix. Convert a data frame of numeric columns with as.matrix(); separate any character columns first so the matrix is purely numeric.
Colours look washed out or saturated
One or two extreme values can stretch the default colour scale. Set an explicit colorRamp2() with breaks that cover the range you care about, as in step 3, or scale the matrix first.
Installation fails
Install through BiocManager::install() and make sure the Bioconductor release matches your R version, as stated on the package page. The package is distributed by Bioconductor, so install.packages("ComplexHeatmap") from CRAN alone is not the documented route.
Large heatmaps produce huge vector files
Rasterise the heatmap body: raster_device accepts png, CairoPNG, agg_png, jpeg, tiff, CairoJPEG and CairoTIFF. Rasterising is controlled by use_raster; setting it to FALSE keeps the body as vector graphics.
Free alternatives
| Tool | Language | What its documentation says |
|---|---|---|
base heatmap() (stats) |
R, included with R | “A heat map is a false color image (basically image(t(x))) with a dendrogram added to the left side and to the top.” Its scale argument takes “row”, “column” or “none”. |
| pheatmap | R, CRAN | “Implementation of heatmaps that offers more control over dimensions and appearance.” Version 1.0.13, GPL-2, when checked. |
| seaborn.clustermap | Python | “Plot a matrix dataset as a hierarchically-clustered heatmap.” Has z_score and standard_scale arguments and row_colors/col_colors for group labels. |
ComplexHeatmap itself is free under the MIT licence. For general plotting in Python, see histograms in Matplotlib; for labelling grouped plots, see label boxplot.
FAQ
What is ComplexHeatmap in R?
An R package from Bioconductor for building heatmaps, arranging several together and attaching annotation graphics to them. It is written by Zuguang Gu and released under the MIT licence.
How do I install ComplexHeatmap?
Run BiocManager::install("ComplexHeatmap") after installing BiocManager from CRAN. See the install section for the exact commands.
Is there a Python version of ComplexHeatmap?
The Bioconductor documentation describes an R package only. Python users commonly turn to seaborn’s clustermap, listed above.
Why does my heatmap not show up inside a loop?
Because Heatmap() only constructs the object. Call draw() on it.
Sources
- ComplexHeatmap, Bioconductor package page (read 2026-11-08)
- ComplexHeatmap Complete Reference, A Single Heatmap (read 2026-11-08)
- ComplexHeatmap Complete Reference, Heatmap Annotations (read 2026-11-08)
- R documentation, stats::heatmap (read 2026-11-08)
- pheatmap on CRAN (read 2026-11-08)
- seaborn.clustermap documentation (read 2026-11-08)







