---
title: "Managing R"
date-meta: 2022-12-12
---

## R startup

Upon startup, R and RStudio look for a few different files used to control the behavior of the R session (e.g., settings options or environment variables). 

In the context of [Posit Team](https://docs.posit.co/posit-team/), these settings are often used to direct Posit Workbench to search for packages in a Posit Package Manager repository.

This section is a practical guide on how to set particular options on R startup. For more information on: 

- How to manage R package environments, refer to the Posit Solutions guide on [Reproducible Environments](https://solutions.posit.co/envs-pkgs/environments/)
- A deeper treatment of R process startup, refer to [What They Forgot to Teach You About R](https://rstats.wtf/r-startup.html)

Here is a summary table of how to control R options and environment variables on startup:

| 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`

The `.Renviron` file is:

- A user-controllable file used to create environment variables.
- Written in a key-value format. Environment variables are created in the format:

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

  - In this example, `Sys.getenv("Key1")` will return `"value1"` in an R session.

- Located at either the user or project level. If there is a project-level `.Renviron` file, the user-level file will not be sourced. 
- Most useful for defining sensitive information like API keys (e.g., 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`.

:::{.callout-tip}
The [`usethis`](https://usethis.r-lib.org/) package includes a helper function for editing `.Renviron` files from an R session with `usethis::edit_r_environ()`. You can specify whether you want to edit the user or project level `.Renviron.`
:::

### `.Rprofile`

The `.Rprofile` file:

- Contains R code that is run when R starts up, after the `.Renviron` file is sourced.
- Is user-controllable, and sets options and environment variables. 
- Can be located either at the user or project level. User-level `.Rprofile` files live in the base of the user's home directory. Project-level `.Rprofile` files live in the base of the project directory.
  - If there is a project-level `.Rprofile` file, the user-level file will not be sourced. In this situtaion, if you want the user-level file to be sourced, explicitly source it at the top of your project-level `.Rprofile` with `source("~/.Rprofile")`.
- Are sourced as regular R code, so setting environment variables must be done inside a `Sys.setenv(key = "value")` call.

A simple example of a `.Rprofile` is:

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

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

:::{.callout-tip}
The [`usethis`](https://usethis.r-lib.org/) package includes a helper function for editing `.Rprofile` files from an R session with `usethis::edit_r_profile()`. You can specify whether you want to edit the user or project level `.Rprofile.`
:::

### `Rprofile.site` and `Renviron.site`

Both `.Rprofile` and `.Renviron` files have equivalents that apply server wide: `Rprofile.site` and`Renviron.site` (no leading dot). These files are:

- Managed by admins on Posit Workbench or RStudio Server.
- Specific to a particular version of R. 
- Most commonly used to manage settings related to package repository access. 
  - For example, administrators generally use the `Rprofile.site` file to implement the [shared-baseline](https://solutions.posit.co/envs-pkgs/environments/shared/) package management strategy.
- Able to be overriden by users in their individual `.Rprofile` or `.Renviron` files.
- 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. 
  - 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`

The `rsession.conf` and `repos.conf` files allow Posit Workbench and RStudio Server administrators to configure particular server-wide R package repositories. 

Only one repository can be configured in `rsession.conf`. If multiple repositories are needed, administrators should use `repos.conf`. Details on configuring Posit Workbench and RStudio Server with these files are in the  [Package Installation section](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html) of the Posit Workbench Admin Guide guide.

## Managing R versions

RStudio requires R version 3.6.0 or higher. Since multiple R versions can be installed side-by-side on a system, RStudio needs to select which version of R to run against. 

### Using `rig` to manage R versions

The simplest way to manage your installed R versions is to use the `rig` R Installation Manager. It works on macOS, Windows, and Linux operating systems. 

For more information and to download it, visit the [`rig`](https://github.com/r-lib/rig?tab=readme-ov-file#the-r-installation-manager) GitHub repository and review the README. 

Once you have installed `rig`, you can use the `rig rstudio` command to start RStudio with a specified R version. For example, to start RStudio with R version 4.3.0, run:

```bash
rig rstudio 4.3.0
```

### Managing R versions manually on Windows

You can override which R version RStudio uses on a Windows machine by navigating to **Tools** > **Global Options** > **General** > **Basic** > **R Sessions**. Select **Change** next to the **R Version** field.

A **Choose R Installation** dialog displays that allows you to select the version of R to use. This dialog box, pictured below, also appears if you hold down the `Ctrl` key at RStudio startup. 

![](images/choose-r-version.png){fig-alt="A screenshot of the dialog box to select an R installation on a Windows operating system." width="450"}
