Skip to main content
v2026.11,986 entries · CC-BY 4.0

ComplexHeatmap in R: Install, Heatmap() and Annotations

Install ComplexHeatmap from Bioconductor, draw an annotated clustered heatmap with Heatmap(), fix colours with colorRamp2(), and read the output.

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.

Ask your first question freeSubscribe

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.

  1. Load the package and build a numeric matrix. Heatmap() takes a matrix, not a data frame; convert with as.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))) 
  2. 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))) 
  3. Fix the colour mapping with colorRamp2(). The reference book says to use circlize::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")) 
  4. Add a column annotation. HeatmapAnnotation() builds the annotation; pass it as top_annotation. A data frame goes in through df, and colours through a named col list:
    group = rep(c("control", "treated"), each = 6) ha = HeatmapAnnotation(df = data.frame(group = group),     col = list(group = c("control" = "grey60", "treated" = "orange"))) 
  5. Create the heatmap. name sets the legend title and identifies the heatmap; column_split cuts the columns into slices:
    ht = Heatmap(mat_z, name = "z-score", col = col_fun,              top_annotation = ha, column_split = group,              column_title = "Simulated expression") 
  6. 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 call draw() explicitly:
    draw(ht) 
  7. 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. With colorRamp2(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 leave col unset, 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. With row_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

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about ComplexHeatmap in R: Install, Heatmap() and Annotations

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →