R Startup

Upon startup, R and RStudio look for a few different files used to control the behavior of the R session, for example by setting options or environment variables. In the context of Posit Team, these settings are often used to set Posit Workbench (previously RStudio Server Pro) to search for packages in an Posit Package Manager repository.

This section is a practical guide on how to set particular options on R startup. General information on how to manage R package environments is available at Reproducible Environments, and a deeper treatment of R process startup is available in What They Forgot to Teach You About R.

Here is a summary table of how to control R options and environment variables on startup. More details are below.

File Who Controls Level Limitations
.Renviron User or Admin User or Project Set environment variables only.
.Rprofile User or Admin User or Project None, sourced as R code.
Rprofile.site Admin Version of R None, sourced as R code.
Renviron.site Admin Version of R Set environment variables only.
rsession.conf Admin Server Only RStudio settings, only single repository.
repos.conf Admin Server Only for setting repositories.

.Renviron

.Renviron is a user-controllable file that can be used to create environment variables. This is especially useful to avoid including credentials like API keys inside R scripts. This file is written in a key-value format, so environment variables are created in the format:

Key1=value1
Key2=value2
...additional key=value pairs

And then Sys.getenv("Key1") will return "value1" in an R session.

Like with the .Rprofile file, .Renviron files can be at either the user or project level. If there is a project-level .Renviron, the user-level file will not be sourced. The usethis package includes a helper function for editing .Renviron files from an R session with usethis::edit_r_environ().

The .Renviron file is most useful for defining sensitive information such as API keys (such as GitHub, Twitter, or Posit Connect) as well as R specific environment variables like the history size (R_HISTSIZE=100000) and default library locations R_LIBS_USER.

.Rprofile

The .Rprofile file contains R code to be run when R starts up. It is run after the .Renviron file is sourced.

.Rprofile files are user-controllable files to set options and environment variables. .Rprofile files can be either at the user or project level. User-level .Rprofile files live in the base of the user’s home directory, and project-level .Rprofile files live in the base of the project directory.

R will source only one .Rprofile file. So if you have both a project-specific .Rprofile file and a user .Rprofile file that you want to use, you explicitly source the user-level .Rprofile at the top of your project-level .Rprofile with source("~/.Rprofile").

.Rprofile files are sourced as regular R code, so setting environment variables must be done inside a Sys.setenv(key = "value") call.

The easiest way to edit your .Rprofile file is to use the usethis::edit_r_profile() function from within an R session. You can specify whether you want to edit the user or project level .Rprofile.

A simple example of a .Rprofile is:

options(repos = c(CRAN = "https://packagemanager.posit.co/all/latest"))

if (interactive()) {
  options(width = 120)
}

Rprofile.site and Renviron.site

Both .Rprofile and .Renviron files have equivalents that apply server wide. Rprofile.site andRenviron.site (no leading dot) files are managed by admins on Posit Workbench or RStudio Server, and are specific to a particular version of R. The most common settings for these files involve access to package repositories. For example, using the shared-baseline package management strategy is generally done from an Rprofile.site.

Users can override settings in these files with their individual .Rprofile files.

These files are set for each version of R and should be located in R_HOME/etc/. R_HOME can be found by running the command R.home(component = "home") in a session of that version of R. So, for example, if R_HOME is /opt/R/4.2.0/lib/R, the Rprofile.site for R 4.2.0 would go in /opt/R/4.2.0/lib/R/etc/Rprofile.site.

rsession.conf and repos.conf

Posit Workbench and RStudio Server allow server admins to configure particular server-wide R package repositories via the rsession.conf and repos.conf files. Only one repository can be configured in rsession.conf. If multiple repositories are needed, repos.conf should be used. Details on configuring Posit Workbench and RStudio Server with these files are in this guide.