[](https://github.com/r-spatial/sf/actions/workflows/R-CMD-check.yaml) [](https://github.com/r-spatial/sf/actions/workflows/tic-db.yml) [](https://app.codecov.io/gh/r-spatial/sf) [](http://www.gnu.org/licenses/gpl-2.0.html) [](https://cran.r-project.org/package=sf) [](https://cran.r-project.org/web/checks/check_results_sf.html) [](https://www.r-pkg.org/pkg/sf) [](https://CRAN.R-project.org/package=sf) # Simple Features for R A package that provides [simple features access](https://en.wikipedia.org/wiki/Simple_Features) for R. [Blogs, links](#blogs-presentations-vignettes-sp-sf-wiki) • [Cheatsheet](#cheatsheet) • [Installing](#installing) • [Contributing](#contributing) • [Acknowledgment](#acknowledgment) • [How to cite](#how-to-cite) Package sf: * represents simple features as records in a `data.frame` or `tibble` with a geometry list-column * represents natively in R all 17 simple feature types for all dimensions (XY, XYZ, XYM, XYZM) * interfaces to [GEOS](https://libgeos.org) for geometrical operations on projected coordinates, and (through R package [s2](https://cran.r-project.org/package=s2)) to [s2geometry](http://s2geometry.io/) for geometrical operations on ellipsoidal coordinates * interfaces to [GDAL](https://gdal.org/), supporting all driver options, `Date` and `POSIXct` and list-columns * interfaces to [PRØJ](http://proj.org/) for coordinate reference system conversion and transformation * uses [well-known-binary](https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary) serialisations written in C++/Rcpp for fast I/O with GDAL and GEOS * reads from and writes to spatial databases such as [PostGIS](http://postgis.net/) using [DBI](https://cran.r-project.org/package=DBI) * is extended by * [lwgeom](https://github.com/r-spatial/lwgeom/) for selected liblwgeom/PostGIS functions * [stars](https://github.com/r-spatial/stars/) for raster data, and raster or vector data cubes (spatial time series) * [sfnetworks](https://luukvdmeer.github.io/sfnetworks/) for geospatial network data (Illustration (c) 2018 by Allison Horst) ## Books, journal articles, blogs, presentations, vignettes, sp-sf wiki * an open access [R Journal article](https://journal.r-project.org/archive/2018/RJ-2018-009/index.html) summarizes the package * two books: [Spatial Data Science: with applications in R](https://r-spatial.org/book/), [Geocomputation with R](https://r.geocompx.org/) * package vignettes: [first](https://r-spatial.github.io/sf/articles/sf1.html), [second](https://r-spatial.github.io/sf/articles/sf2.html), [third](https://r-spatial.github.io/sf/articles/sf3.html), [fourth](https://r-spatial.github.io/sf/articles/sf4.html), [fifth](https://r-spatial.github.io/sf/articles/sf5.html), [sixth](https://r-spatial.github.io/sf/articles/sf6.html), [seventh](https://r-spatial.github.io/sf/articles/sf7.html) * blog posts: [first](https://r-spatial.org/r/2016/02/15/simple-features-for-r.html), [second](https://r-spatial.org/r/2016/07/18/sf2.html), [third](https://r-spatial.org/r/2016/11/02/sfcran.html), [fourth](https://r-spatial.org/r/2017/01/12/newssf.html) * the original R Consortium ISC [proposal](PROPOSAL.md), the R Consortium [blog post](https://www.r-consortium.org/blog/2017/01/03/simple-features-now-on-cran) * presentations: [rstudio::conf 2018](https://edzer.github.io/rstudio_conf/#1) ([video](https://posit.co/resources/videos/tidy-spatial-data-analysis/)), [UseR! 2016](http://pebesma.staff.ifgi.de/pebesma_sfr.pdf) * wiki page describing [sp-sf migration](https://github.com/r-spatial/sf/wiki/Migrating) ## Cheatsheet [CC 4.0](https://creativecommons.org/licenses/by/4.0/) BY [Ryan Garnett](https://github.com/ryangarnett) ## Installing Install either from CRAN with: ```r install.packages("sf") ``` This will install binary packages on Windows and MacOS, unless you configured R such that it tries to install source packages; in that case, see below. Install development versions from GitHub with: ```r library(remotes) install_github("r-spatial/sf") ``` ### Windows Installing sf from source works under Windows when [Rtools](https://cran.r-project.org/bin/windows/Rtools/) is installed. ### MacOS MacOS users are strongly encouraged to install the `sf` binary packages from CRAN, unless they are familiar with compilers, linking, C++ source code, and homebrew. If you experience that R tries to install `sf` from source (or otherwise your install fails but you don't understand what is going on) try again by explicitly installing the binary, using ```r install.packages("sf", type = "binary") ``` The remainder of this section is for those who understand what source installs mean, and imply. Perhaps the easiest way of an install from source is to first install `gdal` using Homebrew. Recent versions of Homebrew include a full-featured up-to-date [gdal formula](https://github.com/Homebrew/homebrew-core/blob/master/Formula/g/gdal.rb), which installs `proj` and `gdal` at the same time: ``` brew install pkg-config brew install gdal ``` Once gdal is installed, you may be able to install `sf` package from source in R. With the current version of `proj` on homebrew, installation requires additional configuration: ```r install.packages("sf", type = "source", configure.args = "--with-proj-lib=$(brew --prefix)/lib/") ``` Or the development version: ```r library(remotes) install_github("r-spatial/sf", configure.args = "--with-proj-lib=$(brew --prefix)/lib/") ``` Alternatively, [these instructions](https://stat.ethz.ch/pipermail/r-sig-mac/2017-June/012429.html) explain how to install gdal using kyngchaos frameworks. For Mac OS 11 Big Sur source install instruction, see [here](https://github.com/r-spatial/sf/issues/1536#issuecomment-727342736) ### Linux For Unix-alikes, GDAL (>= 2.0.1), GEOS (>= 3.4.0) and PROJ (>= 4.8.0) are required. #### Ubuntu Dependencies for recent versions of Ubuntu (18.04 and later) are available in the official repositories; you can install them with: ```sh sudo apt -y update && apt install -y libudunits2-dev libgdal-dev libgeos-dev libproj-dev libsqlite3-dev ``` However, to get more up-to-date versions of dependencies such as GDAL, GEOS and PROJ we recommend adding the [ubuntugis-unstable](http://ppa.launchpad.net/ubuntugis/ubuntugis-unstable/ubuntu/) PPA to the package repositories and installing them as follows: ```sh sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable sudo apt update sudo apt install libudunits2-dev libgdal-dev libgeos-dev libproj-dev libsqlite3-dev ``` Adding this PPA is required for installing `sf` on older versions of Ubuntu (e.g. Xenial). Another option, for advanced users, is to install dependencies from source; see e.g. an older [Travis](https://github.com/r-spatial/sf/blob/593ee48b34001fe3b383ea73ea57063ecf690732/.travis.yml) config file for hints. #### Fedora The following command installs all required dependencies: ```sh sudo dnf install gdal-devel proj-devel geos-devel sqlite-devel udunits2-devel ``` #### Arch Get gdal, proj, geos and podofo from the main repos, and udunits from the AUR: ``` pacman -S gdal proj geos arrow podofo yay/pacaur/yaourt/whatever -S udunits ``` #### `renv` or `conda` There are several reports that `sf` fails to install as a source package when R is used with `renv`, or when R is installed in a `conda` environment. If you experience this, please only raise an issue here if the problem persists without `renv` or `conda`, and otherwise * try to sort this out with the `renv` developers or the `conda` maintainers, or * try to use binary installs of the `sf` package, e.g. from [r2u](https://github.com/eddelbuettel/r2u), or the Posit package manager #### Other To install on Debian, the [rocker geospatial](https://github.com/rocker-org/geospatial) Dockerfiles may be helpful. Ubuntu Dockerfiles are found [here](https://github.com/r-spatial/sf/tree/main/inst/docker). ### Support for (Geo)Parquet and Arrow `sf` links to GDAL, but does not control how GDAL was configured and built. Not every GDAL installation has built-in support for GeoParquet or Arrow. Please see [this issue](https://github.com/r-spatial/sf/issues/2585), or configure and compile GDAL with Parquet support e.g. using [this Dockerfile](https://github.com/r-spatial/sf/tree/main/inst/docker/parquet). ### Multiple GDAL, GEOS and/or PROJ versions on your system If you use dynamic linking (installation from source) and have multiple versions of these libraries installed (e.g. one from ubuntugis-unstable, another installed from source in `/usr/local/lib`) then this will in general not work, even when setting `LD_LIBRARY_PATH` manually. See [here](https://github.com/r-spatial/sf/issues/844) for the reason why. ### lwgeom Functions and methods that require `liblwgeom`, including ellipsoidal (not spherical or Euclidean) metrics (area, distances), are provided by and used from [lwgeom](https://github.com/r-spatial/lwgeom), which is also on [CRAN](https://cran.r-project.org/package=lwgeom). ## Contributing * Contributions of all sorts are most welcome, issues and pull requests are the preferred ways of sharing them. * When contributing pull requests, please adhere to the package style (in package code use `=` rather than `<-`; don't change indentation; tab stops of 4 spaces are preferred). * This project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project, you agree to abide by its terms. ## How to cite Package `sf` can be cited as: * Edzer Pebesma, 2018. Simple Features for R: Standardized Support for Spatial Vector Data. The R Journal [10:1, 439-446.](https://journal.r-project.org/archive/2018/RJ-2018-009/index.html) * Pebesma, E.; Bivand, R. (2023). [Spatial Data Science: With Applications in R](https://r-spatial.org/book/) (1st ed.). 314 pages. [Chapman and Hall/CRC](https://doi.org/10.1201/9780429459016). ## Acknowledgment This project gratefully acknowledges financial [support](https://www.r-consortium.org/projects) from the