6 R Versions
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.2.1 Recommended Installation Directories
RStudio Workbench automatically scans for versions of R at 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
In addition, RStudio Workbench scans all subdirectories of the following directories within
For example, any of the following installed versions of R will be automatically detected by RStudio Workbench:
/opt/R/3.1.0 /opt/R/3.2.0 /opt/local/R/3.1.0 /opt/local/R/3.2.0
If you have versions of R located at other places in the file system, RStudio Workbench can still utilize them. However, you’ll need to explicitly specify their location in a configuration file (this is covered in more detail in the [Using Multiple Versions] section).
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
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
If you want to override which version of R is used, then you can use the
rsession-which-r setting. For example:
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
[*] r-version = /opt/R/3.1.0 [@powerusers] r-version = /opt/R/3.2.0 [jsmith] r-version = /opt/R/3.0.2
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:
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:
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).
18.104.22.168 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:
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 email@example.com.
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.
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:
22.214.171.124 Extended R Version Definitions
/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
|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.|
/etc/rstudio/r-versions file is shown below.
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).
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:
Failure to do so will result in RStudio Workbench being unable to verify the version, which will cause it to be unavailable for use.
126.96.36.199 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
sudo rstudio-server reload
188.8.131.52 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:
6.4.2 Switching Between Versions
To switch between versions of R you use the version menu near the top right of the IDE:
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.
184.108.40.206 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
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:
- If the file
/etc/rstudio/rsession-profileexists, it is sourced.
- If the R Version being loaded specifies a module to load, the user’s
~/.bashrcfile is sourced and the module is loaded using the
- If the R version being loaded specifies a prelauch script to run, it is sourced.
- A bash login shell is created, which sources the
~/.profilescript, whichever is found first to exist (in that order).
- 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.