Installing RStan on Mac or Linux

bgoodri edited this page Jul 16, 2018 · 28 revisions

This page contains instructions for installing RStan for Mac and Linux users only. Windows users should consult the separate instructions at Installing RStan on Windows.


Click the arrows for instructions for installing each prerequisite.

Prerequisite: R

If you already have recent R and RStudio installations (and are not using RStan on a server), skip ahead to the C++ toolchain section.

R installation and version requirements

R version 3.4.0 or later is required, which is available from

Follow the download link, then choose a mirror (we recommend https://cloud.r-project.org/ because it redirects to the closest reliable mirror), then click on the link for your platform. The Linux and Mac versions should install and work with the default configurations.

RStudio (recommended)

Although it is not required, for most users we strongly recommend installing RStudio which has basic support for .stan file types and syntax highlighting for Stan 2.10.0 and higher (if using RStudio version >= 0.99.1259).

Prerequisite: C++ toolchain and configuration

Mac toolchain and configuration

Toolchain

We recommend using the macOS R toolchain installer. Otherwise, to do the steps manually yourself see RStan Mac OS X C++ Toolchain.

Configuration for clang++

After installing the toolchain there is a configuration step. R uses a configuration file called Makevars which contains compiler directives and lives in a hidden directory .R in the user home (login) directory. Running the code chunk below in R will create a .R directory and Makevars file (if they do not already exist) and then configure the recommended compiler flags. This assumes that your toolchain is the one installed in the previous step.

dotR <- file.path(Sys.getenv("HOME"), ".R")
if (!file.exists(dotR)) dir.create(dotR)
MAKEVARS <- file.path(dotR, "Makevars")
if (!file.exists(MAKEVARS)) file.create(MAKEVARS)

cat(
  "\nCXXFLAGS=-O3 -mtune=native -march=native -Wno-unused-variable -Wno-unused-function  -Wno-macro-redefined -Wno-unknown-pragmas",
  "\nCC=clang",
  "CXX=clang++ -arch x86_64 -ftemplate-depth-256",
  file = MAKEVARS, 
  sep = "\n", 
  append = TRUE
)

# print the contents to the console 
cat(readLines(MAKEVARS), sep = "\n")

Notes:

  • Be advised that setting the optimization level to 3 may prevent some other R packages from installing from source if they are only tested with the stock R configuration.
  • If you want to use g++ instead of clang on Mac see the g++ items in the Linux instructions.
Linux toolchain and configuration

Toolchain

For Linux, use your package manager to install build-essential and a recent version of either g++ or clang++. The package libssl-dev (up to version 1.0; version 1.1 brakes package PKI) is required as well.

Config

Running the following code chunk in R will create your personal Makevars file as well as a .R directory in your home directory (if needed) and set some appropriate compiler flags for Stan.

dotR <- file.path(Sys.getenv("HOME"), ".R")
if (!file.exists(dotR)) dir.create(dotR)
MAKEVARS <- file.path(dotR, "Makevars")
if (!file.exists(MAKEVARS)) file.create(MAKEVARS)

cat(
  "\nCXXFLAGS=-O3 -mtune=native -march=native -Wno-unused-variable -Wno-unused-function  -Wno-macro-redefined",
  file = MAKEVARS, 
  sep = "\n", 
  append = TRUE
)

Linux users can also use clang++, but if using g++ these extra instructions may apply:

  • For version 4.9 or higher of g++, in addition to the above commands, we recommend executing the following:

    cat("\nCXXFLAGS+=-flto -Wno-unused-local-typedefs", 
        file = MAKEVARS, sep = "\n", append = TRUE)
  • If you use g++ version 6 or higher, you may want to turn off some verbose warnings that are not relevant to Stan by executing

    cat("\nCXXFLAGS += -Wno-ignored-attributes -Wno-deprecated-declarations", 
        file = MAKEVARS, sep = "\n", append = TRUE)

To print the resulting contents of the Makevars file you can execute

cat(readLines(MAKEVARS), sep = "\n")

Installing RStan

For Mac users RStan can be installed by running the following line in R:

install.packages("rstan", repos = "https://cloud.r-project.org/", dependencies=TRUE)

Make sure not to omit dependencies=TRUE.

Linux users can pick one of two options:

Install RStan binary (Ubuntu)

Ubuntu users can install a binary version of RStan with

# Add marutter's c2d4u repository, (and rrutter for CRAN builds too)
sudo add-apt-repository -y "ppa:marutter/rrutter"
sudo add-apt-repository -y "ppa:marutter/c2d4u"
sudo apt-get update
sudo apt-get install r-cran-rstan
Building from source (Linux or Mac)

For Mac users, we recommend installing the binary version (instructions above), but it is possible to install RStan from source. For most Linux users installing from source will be necessary.

For source builds, you may set the number of processes to use for the build to the number of cores on your machine you want to devote to the build. The default is 1, so using more cores will speed up the build process. For example, to use 4 processes, execute the following in R:

Sys.setenv(MAKEFLAGS = "-j4") 

Compile the downloaded source locally:

install.packages("rstan", type = "source")

Should you use a non-standard compiler for your system (e.g. gcc6 on Mac which defaults to clang), then you need to install RStan and Rcpp from source with

install.packages(c("Rcpp", "rstan"), type = "source")

Should building from source still fail try building as superuser, i.e., by invoking sudo R and repeating the commands above.

Checking your installation

  1. Restart R after the installation and, before loading RStan, verify that no objects created by an older version of RStan are (perhaps auto-)loaded into R.

  2. Verify that your toolchain works by executing the code below in R and checking that it returns the value 10:

fx <- inline::cxxfunction( signature(x = "integer", y = "numeric" ) , '
	return ScalarReal( INTEGER(x)[0] * REAL(y)[0] ) ;
' )

fx( 2L, 5 ) # should be 10
  1. Proceed to How to Use RStan

If you run into an error during installation please visit the Stan Forums.