Chapter 4 Installing NIMBLE

4.1 Requirements to run NIMBLE

You can run NIMBLE on any of the three common operating systems: Linux, Mac OS X, or Windows.

The following are required to run NIMBLE.

  1. R, of course.
  2. The igraph and coda R packages.
  3. A working C++ compiler that NIMBLE can use from R on your system. There are standard open-source C++ compilers that the R community has already made easy to install. See Section 4.2 for instructions. You don’t need to know anything about C++ to use NIMBLE. This must be done before installing NIMBLE.

NIMBLE also uses a couple of C++ libraries that you don’t need to install, as they will already be on your system or are provided by NIMBLE.

  1. The Eigen C++ library for linear algebra. This comes with NIMBLE, or you can use your own copy.
  2. The BLAS and LAPACK numerical libraries. These come with R, but see Section 4.4.3 for how to use a faster version of the BLAS.

Most fairly recent versions of these requirements should work.

4.2 Installing a C++ compiler for NIMBLE to use

NIMBLE needs a C++ compiler and the standard utility make in order to generate and compile C++ for models and algorithms.8

4.2.1 OS X

On OS X, you should install Xcode. The command-line tools, which are available as a smaller installation, should be sufficient. This is freely available from the Apple developer site and the App Store.

For the compiler to work correctly for OS X, the installed R must be for the correct version of OS X. For example, R for Snow Leopard (OS X version 10.8) will attempt to use an incorrect C++ compiler if the installed OS X is actually version 10.9 or higher.

In the somewhat unlikely event you want to install from the source package rather than the CRAN binary package, the easiest approach is to use the source package provided at R-nimble.org. If you do want to install from the source package provided by CRAN, you’ll need to install this gfortran package.

4.2.2 Linux

On Linux, you can install the GNU compiler suite (gcc/g++). You can use the package manager to install pre-built binaries. On Ubuntu, the following command will install or update make, gcc and libc.

sudo apt-get install build-essential

4.2.3 Windows

On Windows, you should download and install Rtools.exe available from https://cran.r-project.org/bin/windows/Rtools/. Select the appropriate executable corresponding to your version of R (and follow the urge to update your version of R if you notice it is not the most recent). This installer leads you through several ‘pages’. We think you can accept the defaults with one exception: check the PATH checkbox (page 5) so that the installer will add the location of the C++ compiler and related tools to your system’s PATH, ensuring that R can find them. After you click ‘Next’, you will get a page with a window for customizing the new PATH variable. You shouldn’t need to do anything there, so you can simply click ‘Next’ again.

The checkbox for the ‘R 2.15+ toolchain’ (page 4) must be checked (in order to have gcc/g++, make, etc. installed). This should be checked by default.

4.3 Installing the NIMBLE package

Since NIMBLE is an R package, you can install it in the usual way, via install.packages("nimble") in R or using the R CMD INSTALL method if you download the package source directly.

NIMBLE can also be obtained from the NIMBLE website. To install from our website, please see our Download page for the specific invocation of install.packages.

4.3.1 Problems with installation

We have tested the installation on the three commonly used platforms – MacOS, Linux, Windows9. We don’t anticipate problems with installation, but we want to hear about any and help resolve them. Please post about installation problems to the nimble-users Google group or email nimble.stats@gmail.com.

4.4 Customizing your installation

For most installations, you can ignore low-level details. However, there are some options that some users may want to utilize.

4.4.1 Using your own copy of Eigen

NIMBLE uses the Eigen C++ template library for linear algebra. Version 3.2.1 of Eigen is included in the NIMBLE package and that version will be used unless the package’s configuration script finds another version on the machine. This works well, and the following is only relevant if you want to use a different (e.g., newer) version.

The configuration script looks in the standard include directories, e.g. /usr/include and /usr/local/include for the header file Eigen/Dense. You can specify a particular location in either of two ways:

  1. Set the environment variable EIGEN_DIR before installing the R package, for example: export EIGEN_DIR=/usr/include/eigen3 in the bash shell.
  2. Use R CMD INSTALL --configure-args='--with-eigen=/path/to/eigen' nimble_VERSION.tar.gz or install.packages("nimble", configure.args = "--with-eigen=/path/to/eigen")

In these cases, the directory should be the full path to the directory that contains the Eigen directory, e.g., /usr/include/eigen3. It is not the full path to the Eigen directory itself, i.e., NOT /usr/include/eigen3/Eigen.

4.4.2 Using libnimble

NIMBLE generates specialized C++ code for user-specified models and nimbleFunctions. This code uses some NIMBLE C++ library classes and functions. By default, on Linux the library code is compiled once as a linkable library - libnimble.so. This single instance of the library is then linked with the code for each generated model. In contrast, the default for Windows and Mac OS X is to compile the library code as a static library - libnimble.a - that is compiled into each model’s and each algorithm’s own dynamically loadable library (DLL). This does repeat the same code across models and so occupies more memory. There may be a marginal speed advantage. If one would like to enable the linkable library in place of the static library (do this only on Mac OS X and other UNIX variants and not on Windows), one can install the source package with the configuration argument --enable-dylib set to true. First obtain the NIMBLE source package (which will have the extension .tar.gz from our website and then install as follows, replacing VERSION with the appropriate version number:

R CMD INSTALL --configure-args='--enable-dylib=true' nimble_VERSION.tar.gz

4.4.3 BLAS and LAPACK

NIMBLE also uses BLAS and LAPACK for some of its linear algebra (in particular calculating density values and generating random samples from multivariate distributions). NIMBLE will use the same BLAS and LAPACK installed on your system that R uses. Note that a fast (and where appropriate, threaded) BLAS can greatly increase the speed of linear algebra calculations. See Section A.3.1 of the R Installation and Administration manual available on CRAN for more details on providing a fast BLAS for your R installation.

4.4.4 Customizing compilation of the NIMBLE-generated C++

For each model or nimbleFunction, NIMBLE can generate and compile C++. To compile generated C++, NIMBLE makes system calls starting with R CMD SHLIB and therefore uses the regular R configuration in ${R_HOME}/etc/${R_ARCH}/Makeconf. NIMBLE places a Makevars file in the directory in which the code is generated, and R CMD SHLIB uses this file as usual.

In all but specialized cases, the general compilation mechanism will suffice. However, one can customize this. One can specify the location of an alternative Makevars (or Makevars.win) file to use. Such an alternative file should define the variables PKG_CPPFLAGS and PKG_LIBS. These should contain, respectively, the pre-processor flag to locate the NIMBLE include directory, and the necessary libraries to link against (and their location as necessary), e.g., Rlapack and Rblas on Windows, and libnimble. Advanced users can also change their default compilers by editing the Makevars file, see Section 1.2.1 of the Writing R Extensions manual available on CRAN.

Use of this file allows users to specify additional compilation and linking flags. See the Writing R Extensions manual for more details of how this can be used and what it can contain.


  1. This differs from most packages, which might need a C++ compiler only when the package is built. If you normally install R packages using install.packages on Windows or OS X, the package arrives already built to your system.

  2. We’ve tested NIMBLE on Windows 7, 8 and 10.