6 R Versions

6.1 Overview

RStudio Workbench enables users and administrators to have very fine-grained control over which versions of R are used in various contexts. Capabilities include:

  • Administrators can install several versions of R and specify a global default version as well as per-user or per-group default versions.

  • Users can switch between any of the available versions of R as they like.

  • Users can specify that individual R projects remember their last version of R and always use that version until explicitly migrated to a new version.

Flexible control over R versions makes it much easier to provide upgraded versions of R for users (or individual projects) that require them; while at the same time not disrupting work that requires continued use of older versions.

6.2 Installing R

We recommend installing multiple versions of R because an environment with multiple versions of R helps provide a stable, reproducible environment for your R developers.

Install R using the directions at https://docs.rstudio.com/resources/install-r/.

6.3 Configuring the Default Version of R

When multiple versions of R are installed you will need to specify which version is the default one for new R sessions. This can be done automatically via the system PATH. However, several other mechanisms are provided when more flexibility is required.

6.3.1 Single Default Version of R

RStudio uses the version of R pointed to by the output of the following command:

$ which R

The which command performs a search for the R executable using the system PATH. RStudio will therefore by default bind to the same version that is run when R is executed from a terminal.

For versions of R installed by system package managers this will be /usr/lib/R. For versions of R installed from source this will typically (but not always) be /usr/local/lib/R.

If you want to override which version of R is used, then you can use the rsession-which-r setting. For example:

/etc/rstudio/rserver.conf

rsession-which-r=/usr/local/lib/R

Note: This change will not take effect until the server is restarted.

6.3.2 Default Version Per User or Group

You can use the User and Group Profiles feature to specify distinct default versions of R for various users and groups. For example, the following profile configuration uses R 3.1.0 as the system default, R 3.2.0 for the powerusers group, and R 3.0.2 for the user jsmith:

[*]
r-version = /opt/R/3.1.0

[@powerusers]
r-version = /opt/R/3.2.0

[jsmith]
r-version = /opt/R/3.0.2

Note that r-version specifies the full path to the directory where R is installed.

6.3.3 User Configurable Default Version

Users can also configure their own default version of R. This is done using the General pane of the Global Options dialog:

Set Default R Version

Set Default R Version

See the Disabling Use of Multiple Versions section for details on how to disable version switching entirely either system-wide or on a per-user or per-group basis.

6.4 Using Multiple Versions of R Concurrently

6.4.1 Determining Available Versions

RStudio Workbench scans for and automatically discovers versions of R in the following locations:

/usr/lib/R
/usr/lib64/R
/usr/local/lib/R
/usr/local/lib64/R
/opt/local/lib/R
/opt/local/lib64/R
/opt/R/*
/opt/local/R/*

This is described in more detail in the Recommended Installation Directories section. If you have installed versions of R in alternate locations, you can list them within the /etc/rstudio/r-versions configuration file. For example:

/etc/rstudio/r-versions

/opt/R-3.2.1
/opt/R-devel-3.3

In addition, any version of R referenced in an r-version directive within User and Group Profiles is also recognized.

In order to be usable, the R home path must be readable by the RStudio server account (usually rstudio-server; see Access and Security for details).

6.4.1.1 Version Scan Report

At startup, RStudio Workbench collects information about each available R version as described above, and writes a report to the following file in JSON format:

/var/lib/rstudio-server/r-versions

This file is later read by the various RStudio processes responsible for displaying and switching between R versions. If you aren’t seeing the R versions look and work as you expect, the content of this file can give you some insight into RStudio’s understanding of your system’s configuration. If you’re unable to resolve the issue, include the contents of the file when submitting a support ticket to .

Note that the JSON format of the r-versions file is subject to change between RStudio versions, so avoid reading or using it in automated tooling.

The r-versions file must be available on all nodes that run R sessions. We don’t generally recommend changing its location, but if you need to do so in order to mount it on R session nodes, you can do via the r-versions-path option as in the following example:

/etc/rstudio/rserver.conf

r-versions-path=/mnt/config/rstudio-server/r-versions

6.4.1.2 Extended R Version Definitions

The /etc/rstudio/r-versions file allows you to specify extended information for a particular R Version, providing you:

  • The ability to specify additional environment variables to set
  • An optional preload script to run
  • An optional environment module to load (more info here)
  • A user-friendly label name for the version that is displayed in the UI

To specify extended format information, modify the /etc/rstudio/r-versions file to consist of multiple R entries separated by a blank line. The following table lists the fields that are available for each R entry in the file.

Path (Required if Module not specified, see Modules) The root directory of the location of the R installation.
Label (Optional) The user-friendly name for the R version that will be displayed to users in the UI.
Module (Optional) The name of an environment module to load for the R version. This is loaded by running the command module load [module] after sourcing the user’s .bashrc file.
Script (Optional) A script to run once the environment has been loaded but before the session process has been launched.
Repo (Optional) A string representing a CRAN Repository URL, or the path to a repos.conf file which lists multiple package repositories. See CRAN Repositories for more information.
Library (Optional) A : separated list of directories which house the desired R packages for the particular R version. Overrides the R_LIBS_SITE environment variable. This will be combined with R_LIBS_USER when forming the R library paths. Most R installations use a default site library located at $R_HOME/site-library, so you may need to include the default site library path directories when setting this field.

An example /etc/rstudio/r-versions file is shown below.

/etc/rstudio/r-versions

Path: /opt/R/R-2.15.3
Label: My special R Version
Module: testmodule
Script: ~/rload.sh
Repo: https://cran.ms.unimelb.edu.au/
Library: /share/packages/R-2.15.3

Path: /opt/R/R-2.15.3-alternate
Label: My special R Version 2

Module: r/latest
Label: Latest version of R

/opt/misc/R/SpecialR1
/opt/misc/R/SpecialR2
/opt/mic/R/AltnerateR

It is important that each entry consists of the fields as specified above. Each field must go on its own line. There should be no empty lines between field definitions.

Each R entry must be separated by one full blank line (two new-line \n characters). If only the path is being specified, with no label, script, or module, you may simply list the path to the installation (as in previous versions). Paths are not separated by a blank line, but they must be separate from extended definitions by a blank line (as in the above example).

6.4.1.2.1 Modules

By setting the name of a module in an environment definition, that version of R will be loaded entirely by module. When a module is defined and the Path is not specified, the default R binary on the path will be used once the module is loaded. Otherwise, if Path is specified, that specific binary will be used.

If you do not specify a Path to the R installation, you must ensure that RStudio Workbench can load the module by specifying the location of the module shell initialization script for sh. For example:

/etc/rstudio/rserver.conf

modules-bin-path=/usr/local/Modules/3.2.9/init/sh

Failure to do so will result in RStudio Workbench being unable to verify the version, which will cause it to be unavailable for use.

6.4.1.3 Reloading Configuration

In order for the changes to the /etc/rstudio/r-versions file to be detected, you must either restart RStudio (via sudo rstudio-server restart) or send the SIGHUP message to the rserver process. This can be done using kill -s SIGHUP to the server process, or via the reload command:

sudo rstudio-server reload

6.4.1.4 Excluding Versions

If you have versions of R on your system that would normally be picked up by automatic scanning but which you’d like to exclude, the most straightforward thing to do is to disable R version scanning altogether and explicitly specify all versions you’d like to use in /etc/rstudio/r-versions. For example:

/etc/rstudio/rserver.conf

r-versions-scan=0

6.4.2 Switching Between Versions

To switch between versions of R you use the version menu near the top right of the IDE:

Switching Versions

Switching Versions

After switching, the specified version will be used for the duration of the current session (see the section on Multiple R Sessions for more details on the lifetime of sessions). Newly created R sessions will continue to use whatever default R version has been configured for the user.

6.4.2.1 Preserving Versions for Projects

It’s often useful to preserve the version used within an R project irrespective of whatever the current default R version is for a user. This is in fact the behavior by default for RStudio projects however can be changed from the General pane of the Global Options dialog.

This configuration enables users to easily migrate projects one-by-one to a new version of R after it’s been confirmed that all the code continues to work as expected under the new version.

6.4.3 Disabling Use of Multiple Versions

If you want to prevent users from being able to change R versions entirely you can use the r-versions-multiple option:

/etc/rstudio/rserver.conf

r-versions-multiple=0

You can also configure this on a per-user or per-group basis by specifying the r-versions-multiple option within User and Group Profiles.

6.5 Managing Upgrades of R

There are various ways to handle upgrades to new versions of R ranging from allowing each user to control exactly when they upgrade all the way to forcing everyone to upgrade all at once.

By combining the various options described above you can create a highly customized upgrade policy that reflects both your internal policies and the preferences of your users.

6.5.1 User Controlled Migration

The most conservative approach is to start with a default version of R and preserve that default for the lifetime of the server. In this configuration you can continue to install new versions of R as they are released however users won’t ever run those new versions unless they make an explicit gesture to do so. See the User Configurable Default Version and Switching Between Versions sections for details on how users can explicitly switch versions.

6.5.2 Partial Migration

If your posture towards new R versions is that you’d like users to migrate to the new version(s) as quickly as is convenient you can be more aggressive in how you introduce them. In this scenario you might use the Default Version Per User or Group feature to migrate a portion of new users immediately but preserve older versions for those who request it.

Note that in this scenario R projects will still preserve their previous R version so long as users have enabled the option described in Preserving Versions for Projects.

6.5.3 Full Migration

The most aggressive approach is to force all users to upgrade to the new R version immediately (this is essentially what happens in the open-source version of RStudio Server). To implement this you’d set a Single Default Version of R as well as disabling the use multiple versions as described in Disabling Use of Multiple Versions.

Note that via User and Group Profiles you could also have a subset of R users that are always fully migrated to new versions while preserving user controlled migration or partial migration for others.

6.6 Session Initialization

In the preceding sections, we described how to allow the server to discover multiple versions of R to be used by the user. The R environment is loaded before the session begins execution, and several files are executed along the way that can cause problems with your R Environment if any variables are incorrectly set.

When a session is launched, the following steps occur:

  1. If the file /etc/rstudio/rsession-profile exists, it is sourced.
  2. If the R Version being loaded specifies a module to load, the user’s ~/.bashrc file is sourced and the module is loaded using the module load command.
  3. If the R version being loaded specifies a prelauch script to run, it is sourced.
  4. A bash login shell is created, which sources the ~/.bash_profile, ~/.bash_login or the ~/.profile script, whichever is found first to exist (in that order).
  5. The session is launched with the environment constructed in steps 1-4.

As you can see, there are many different scripts which can affect the R environment which gets initialized when starting a new session, so play close attention to how these scripts could be affecting your particular environment.