8  R Startup

R has been designed to be used from shared computing resources such as linux servers. As a result R’s startup offers lots of opportunity for customization; both for every user of a system as well as for each individual user. However this flexibility comes at a cost: complexity.

And for sure, R’s startup procedures are complex:

R Startup flowchart. DNE = does not exist. Original by Thomas Lin Pedersen

R Startup flowchart. DNE = does not exist. Original by Thomas Lin Pedersen

However most R users can ignore the majority of this complexity and focus on two main files.

  1. .Renviron - which contains environment variables to be set in R sessions.
  2. .Rprofile - which contains R code to be run in each session.

These files are R specific instances of a broader family of customization files commonly referred to as dotfiles. These are used to tailor the behavior of many programs, particularly those with roots in the unix command line.

Many people store their dotfiles on GitHub and a great way to find inspiration for what you can do with them is to browse other people’s dotfile repositories.

One way to find R specific dotfiles is to do a GitHub search for filename:.Rprofile.

8.1 .Renviron

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

The .Renviron file contains lists of environment variables to set. This is not R code, it uses a format similar to that used on the command line shell.

The easiest way to edit .Renviron is by running usethis::edit_r_environ().

A simple example of a .Renviron file is:


Try the activity usethis::use_course("rstd.io/wtf-source-package")

to learn how to set a GitHub PAT to your .Renviron and then use it with usethis::use_github() to upload a project to GitHub.

8.2 .Rprofile

The .Rprofile file contains R code to be run when R starts up. It is run after the .Renviron file is sourced. Typically .Rprofile is located in the users’ home directory (~/.Rprofile), however a different location can be configured by setting the R_PROFILE_USER environment variable.

The easiest way to edit .Rprofile is by running usethis::edit_r_profile().

Some common things people often add to their .RProfile

  1. Set a default CRAN mirror
  2. Write a welcome message
  3. Customize their R prompt
  4. Change options, screen width, numeric display
  5. Load frequently used packages (but be very careful)
  6. Aliases / shortcuts for frequently used functions

8.2.1 Reproducibility

A good rule of thumb is you should only put things in your .Rprofile that you run interactively in the R terminal. If it ever appears in a R script or R Markdown file it should not be in your .Rprofile.

If you set these options in your .Rprofile, then try to run one of your scripts on another system without your .Rprofile it will no longer be reproducible. Some problematic examples are loading packages used in analysis (such as dplyr or ggplot2) or changing default options which change the value of outputs, such as options(stringsAsFactors = FALSE).

In addition because the .Rprofile is run by every R process (including those started by R itself) it is important to guard most of the code with interactive(), so it is only run in interactive sessions (sessions you are controlling with a terminal).

A simple example of a .Rprofile is:

options(repos = c(CRAN = "https://cran.rstudio.org"))

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

Try the activity usethis::use_course("rstd.io/wtf-source-package")

to learn how to create a .Rprofile with a default CRAN repository and add a startup message to it.

8.3 Disabling startup files

You can run R without any startup files by using the --vanilla argument when starting R. In RStudio you can do this by checking the option Project Options -> Disable .Rprofile execution on session start / resume. You can also selectively disable only the user or site .Rprofile with --no-init-file and --no-site-file respectively, and disable the environment files with --no-environ.


Both .Renviron and .Rprofile must end with a newline character. If they do not the last line will be ignored without a warning or error.