# tmap: thematic maps in R with a ggplot2-shaped syntax

> tmap draws thematic maps in R through a layered grammar borrowed from ggplot2, and the install is easy on CRAN but conditional on the GEOS, GDAL and PROJ system libraries.

**r-tmap/tmap** — R package for thematic maps

- Repository: https://github.com/r-tmap/tmap
- Website: https://r-tmap.github.io/tmap
- Stars: 908 · Forks: 124
- Language: R
- License: GPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/r-tmap-tmap

## A layered grammar borrowed from the chart world

tmap is an R package for drawing thematic maps, and the design decision that shapes everything else is that its API follows A Layered Grammar of Graphics and deliberately resembles the syntax of ggplot2. The project page names ggplot2 as a popular R library for drawing charts, and tmap takes the same idea, layer by layer, into cartography. For an R user the transfer is close to free: the same mental model of adding pieces with the plus operator, and a similar vocabulary of shapes, scales and legends, but the vocabulary is remapped to spatial objects. The consequence is that tmap and ggplot2 are complements rather than competitors. ggplot2 draws charts, tmap draws maps, and a chart that happens to be a map, such as a choropleth, is a chart layer for which ggplot2 has no native answer. The layered approach also means a tmap script is a description of the final map rather than a sequence of drawing calls.

## tm_shape() anchors the data, tm_polygons() draws the layer

The smallest useful tmap expression is two calls joined by a plus. The first example in the project page plots the happy planet index per country, using the World object that ships inside the package as example spatial data in sf format:

```r
tm_shape(World) +
    tm_polygons(fill = "HPI")
```

tm_shape() is the anchor: it names the spatial object and, optionally, the coordinate reference system. tm_polygons() is the layer that fills geometry with a variable, here the HPI column. Everything else in the API is more layers of the same kind. The example scripts in the repository make the surface concrete, with dedicated files for circles, lines, raster, text, grid, compass, credits, facets, inset maps, animations, basemaps, patterns, colour scales and legends. A call that starts as a choropleth can therefore grow into a small map composition without leaving the grammar, and the plus-operator style means the layers stay in the order they were written.

## Installing tmap from CRAN and from source

The stable install is a single call, and the project page calls it straightforward:

```r
install.packages("tmap")
```

For the development version the project page lists three routes. Two come from GitHub, with remotes and with pak:

```r
# install.packages("remotes")
remotes::install_github("r-tmap/tmap")

# install.packages("pak")
pak::pak("r-tmap/tmap")
```

The third pulls the same package from the project r-universe repository, listed ahead of the main CRAN mirror:

```r
install.packages("tmap", repos = c("https://r-tmap.r-universe.dev", "https://cloud.r-project.org"))
```

The commented install.packages lines in that snippet are the maintainers telling you which helper to install first, since neither remotes nor pak ships with R itself. One detail worth noticing: the project page includes a CRAN checks badge, which links to the check results for the package, so the state of the current release against the CRAN policies is published rather than something you have to ask about.

## GEOS, GDAL, PROJ, Abseil and OpenSSL decide whether the install works

Most R dependencies install themselves, and the project page says tmap's package dependencies come along automatically. Two of them do not behave that way. sf and s2 carry additional system requirements, and the project page notes that for Windows users these are installed along with the packages, while for Linux and MacOS users the additional libraries may have to be installed manually. That single sentence is where most failed installs come from, and it is the reason the page adds a paragraph on failure. sf requires GEOS, GDAL and PROJ, and the page points at the terra installation instructions for those three, for MacOS and for Linux, noting that terra needs the same libraries. s2 requires Abseil and OpenSSL, and the page links the s2 installation instructions. The practical check before you start is whether those five system libraries are already on the machine, which is usually the case for a spatial R setup and usually not the case for a fresh analysis container.

## A 4.x package with a small, tidy repository layout

The repository root shows a conventional R package: DESCRIPTION, NAMESPACE, LICENSE, R/ for the code, man/ for documentation, vignettes/, tests/, examples/, inst/, data/ and data-raw/, plus README.Rmd alongside the generated README.md and a tmap.Rproj project file. Two entries are less usual. A pkgdown/ directory and a _pkgdown.yml configuration sit at the root, which is how the documentation site at r-tmap.github.io is built, and there is a sandbox/ directory. The version numbering tells the other story: releases v4.0 on 2025-01-28, then 4.4 and 4.4-1 both on 2026-06-26. The patch release landing on the same day as 4.4 suggests the two were published together, which is a packaging detail rather than a feature signal. The continuous integration badge points at an R-CMD-check workflow and a Codecov badge tracks test coverage, so the package is tested against the R CMD check machinery that CRAN itself uses.

## Where tmap differs from the alternatives on the table

Two comparisons are worth making. The first is with ggplot2, which the project page names as the package whose syntax tmap resembles. The difference in approach is the subject matter and the layer set: ggplot2 draws charts from a data frame, while tmap draws spatial objects and adds the layers a map needs, such as a coordinate system chosen at the shape stage, legends with an orientation, a grid, a compass, credits, inset maps, basemaps, patterns and animation. Keeping the chart layer and the map layer in the same drawing system is the reason to pick tmap over building a map out of chart primitives. The second comparison is with terra, which the project page mentions while explaining the system libraries. terra is not presented as a substitute here, it is presented as a peer that needs the same GEOS, GDAL and PROJ libraries and as the source of the installation instructions to follow. A team that already has terra working on a machine has the expensive half of the tmap prerequisites in place, which makes the decision much closer to a package install than a system administration task.

## Licence, learning resources and the 2D habit

tmap is distributed under the GNU General Public License version 3, as the licence badge and the LICENSE file in the repository root both record, so a commercial distribution of a pipeline that bundles tmap needs a licence review before it ships, not after. Beyond the code, the project points at three learning routes: a chapter on making maps with R inside the Geocomputation with R book, the official vignettes at r-tmap.github.io covering basic and advanced topics with examples, and a book in progress on spatial data visualisation with tmap at tmap.geocompx.org. That is a well documented package for a domain where documentation usually thins out. The one limitation to keep in view is scope. The repository has a dedicated file for raster layers and for RGB imagery, so raster input is handled, but the package is built around sf objects and vector geometry, and a workflow that starts and ends on raster data belongs with a raster-first tool rather than with tmap.

## Conclusion

tmap suits an R team that already works with sf objects and wants a map syntax close to ggplot2, and it does not suit a workflow that needs to draw maps without the sf and s2 stack, or one that needs raster-first tooling. Verify three things before you commit: that GEOS, GDAL and PROJ are present on the machine, since the README says Linux and MacOS users may have to install them by hand, that Abseil and OpenSSL are available for s2, and that the 4.x line, released as 4.4 and 4.4-1 on 2026-06-26, matches the code your scripts already call.

## FAQ

### How do I install tmap in R?

The current release is on CRAN and installs with install.packages("tmap"). Development versions can come from GitHub with remotes::install_github("r-tmap/tmap") or pak::pak("r-tmap/tmap"), or from the project r-universe repository.

### What system libraries does tmap need on Linux or MacOS?

The project page says sf requires GEOS, GDAL and PROJ, and s2 requires Abseil and OpenSSL. Windows users get these installed along with the packages, while Linux and MacOS users may need to install the additional libraries manually.

### How is the tmap API different from ggplot2?

tmap follows a layered grammar of graphics and its syntax resembles ggplot2, but it adds map specific layers such as a coordinate system, legends, a grid, a compass, inset maps, basemaps, patterns and animation, and it draws sf spatial objects.

### What licence is tmap released under?

The licence file in the repository root and the project badge both record the GNU General Public License version 3.

## Sources

- [License: GPL-3.0](https://github.com/r-tmap/tmap/blob/master/LICENSE)
- [Project website](https://r-tmap.github.io/tmap)
- [README](https://github.com/r-tmap/tmap/blob/master/README.md)
- [Releases](https://github.com/r-tmap/tmap/releases)
- [r-tmap/tmap on GitHub](https://github.com/r-tmap/tmap)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/r-tmap-tmap