# terra is the R spatial package that makes GDAL someone else's problem

> terra is an R package for spatial data analysis, with a C++ core that wraps the usual geospatial system libraries, and the installation instructions are really a checklist of what has to be present on your machine first. The CRAN build is old, the development branch is not, and the C++ library underneath can be used on its own.

**rspatial/terra** — R package for spatial data handling https://rspatial.github.io/terra/reference/terra-package.html

- Repository: https://github.com/rspatial/terra
- Stars: 622 · Forks: 107
- Language: C++
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/rspatial-terra

## A spatial package with a C++ core

terra is an R package for spatial data analysis, and the primary language of the repository is C++, which tells you where the work happens. The R directory holds the user facing functions, the src directory holds the compiled core, and the man directory holds the documentation, with a NAMESPACE file controlling what is exported and a DESCRIPTION file describing the package to R itself. The public entry point is the documentation page, and the readme points at tutorials hosted on the project's site, a cheatsheet available as a web page and as a PDF, and a Stack Overflow tag for questions. That combination is the shape of a package that has been around long enough to have a large user base, since a cheatsheet and a tag only accumulate when people keep using the thing. The repository also carries the usual packaging furniture for a serious R package, with a configure script and configure.ac, a cleanup script, a pkgdown configuration for the documentation site, a NEWS file and a tests directory.

## Four installation routes, and the one you probably want

The install section offers the released version, the development version, and a source build, with the source build differing per operating system. The released version comes from CRAN, and the development version is easiest on Windows or macOS through the R-universe service.

```r
install.packages('terra', repos='https://rspatial.r-universe.dev')
```

For a source build you first need Rcpp, which terra depends on, and then the operating system specific steps.

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

On Windows you need Rtools, which provides the C++ compiler that R can use, with current versions of both R and Rtools, and then you install from GitHub.

```r
remotes::install_github("rspatial/terra")
```

The practical decision here is which build you pin. The CRAN build is the reproducible one and the development build is where new work lands, and a project that has to run the same analysis on several machines is better off on the released version until it needs something specific from the newer one.

## On Linux the real checklist is the system libraries

The Linux instructions split into an easy way and a harder way, and the hard way is the informative one. The easy way on Ubuntu is r2u, which packages the binary and system dependencies for Ubuntu in a way that avoids compiling. The harder way lists what the machine needs: GDAL at 2.2.3 or newer, GEOS at 3.4.0 or newer, PROJ at 4.9.3 or newer, netcdf at 4.1.3 or newer, along with sqlite3 and tbb.

```bash
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install libgdal-dev libgeos-dev libproj-dev libtbb-dev libnetcdf-dev
```

That is the real shape of the dependency, and it is worth being blunt about it: terra is not a self contained package, it is a front end to a stack of geospatial system libraries that you either already have or now have to install. The readme also points at the instructions for the sf package, which cover other Linux distributions and the case where the versions above need updating. The thread pool library in that list is the one people forget, and it is the difference between a spatial workflow that scales and one that does not.

## macOS needs the PROJ path spelled out

On macOS the readme offers MacPorts or Homebrew, and the difference between them is a single configuration argument. With MacPorts the install is one command, because the package is already in the ports tree with its dependencies resolved.

```bash
sudo port install R-terra
```

With Homebrew you need the geospatial libraries first, and then the path to the PROJ library has to be passed to the configure step, because Homebrew does not install into a location the default build script looks in.

```bash
brew install pkg-config
brew install gdal proj
```

```r
remotes::install_github("rspatial/terra", configure.args = "--with-proj-lib=$(brew --prefix)/lib/")
```

The same argument is needed when building the CRAN version from source on macOS, with the type argument set to source. The repeated emphasis on this one flag in the instructions is a hint about where the install friction actually is on that platform.

## The C++ library underneath is a separate thing you can use

The readme closes by pointing at two ways to use terra's capabilities outside R. The first is tappa, a separate project that provides the terra functionality in Python, which matters because a lot of geospatial pipelines are Python and a hard dependency on R is a barrier. The second is the C++ library itself, with a directory in the repository for a command line application that shows how to roll your own program against it. The existence of that directory is a statement about the design. terra is not only an R package with a C++ implementation, it is a C++ library with an R binding, and the tree reflects that with a separate application directory, a configure script and a src tree of its own. If your requirement is an R package, ignore both; if your requirement is a Python script or a standalone tool, they are the two documented paths rather than something you have to work out from the source.

## The CRAN release is old, and the repository is not

The release list has a single entry, the CRAN build of version 1.5-16, dated 2022-01-30, while the last push to the default branch was on 2026-10-20. That gap is the most important fact about the project for an adopter. The CRAN version that install.packages gives you by default is more than four years old, and everything that has changed since then is in the development branch, reachable through the R-universe build or from source. The readme does not explain why the CRAN version has not moved, and it is worth considering the usual reasons before you assume a problem, since a package with a C++ core and a set of system library constraints has a much harder time being accepted for a new CRAN release than a pure R package does. The CI badge in the readme points at a package check workflow, so the development branch is being validated continuously even though the released artefact has not moved. For a team that needs a current version, the R-universe build is the one to use, and it is worth recording which build a result came from.

## Conclusion

terra earns its place for an R analyst who has to move between raster and vector data without leaving R, since it exposes the same underlying geospatial stack that the wider ecosystem uses, and the tutorials and cheatsheet mean the learning curve is mostly about terra's own naming rather than about geospatial theory. It is the wrong choice if you want a self contained install with no system dependencies, because the package needs GDAL, GEOS, PROJ, netcdf, sqlite3 and tbb present on the machine, and it is the wrong choice if you need the newest features today, since the CRAN build is from 2022 while the repository is actively maintained. Verify three things before you install: which build you want, since CRAN and the R-universe development version behave differently, that the system libraries on your machine meet the stated minimum versions, and whether your platform has a packaged path, since Ubuntu users can take the r2u route and macOS users can take a MacPorts package. The licence is GPL-3.0 and the last push was on 2026-10-20.

## FAQ

### What are the system requirements for terra?

The Linux instructions list GDAL 2.2.3 or newer, GEOS 3.4.0 or newer, PROJ 4.9.3 or newer, netcdf 4.1.3 or newer, plus sqlite3 and tbb, with a note that the sf package instructions cover other distributions and version updates.

### How do I install the development version of terra?

The easiest route on Windows and macOS is the R-universe service, using install.packages with the rspatial.r-universe.dev repository. Building from source needs Rcpp first, plus Rtools on Windows, MacPorts or Homebrew on macOS with a PROJ path argument, and the system libraries on Linux.

### Can I use terra outside R?

The readme points to tappa, a separate project that provides the terra functionality in Python, and to the C++ library itself, with a directory in the repository showing how to build your own application against it.

### How current is the released version of terra?

The only release listed is the CRAN build 1.5-16 from 2022-01-30, while the repository is actively maintained with a last push on 2026-10-20. Newer work is available through the R-universe development build rather than through CRAN.

## Sources

- [Issues](https://github.com/rspatial/terra/issues)
- [License: GPL-3.0](https://github.com/rspatial/terra/blob/master/LICENSE)
- [README](https://github.com/rspatial/terra/blob/master/README.md)
- [Releases](https://github.com/rspatial/terra/releases)
- [rspatial/terra on GitHub](https://github.com/rspatial/terra)

---

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