R: Initialization at Start of an R Session

Startup {base} | R Documentation

## Initialization at Start of an R Session

### Description

In R, the startup mechanism is as follows.

Unless `--no-environ` was given on the command line, R searches for user and site files to process for setting environment variables. The name of the site file is the one pointed to by the environment variable `R_ENVIRON`; if this is unset or empty, ‘`$R_HOME/etc/Renviron.site`’ is used (if it exists, which it does not in a “factory-fresh” installation). The user files searched for are ‘`.Renviron`’ in the current or in the user's home directory (in that order). See Details for how the files are read.

Then R searches for the site-wide startup profile unless the command line option `--no-site-file` was given. The name of this file is taken from the value of the `R_PROFILE` environment variable. If this variable is unset, the default is ‘`$R_HOME/etc/Rprofile.site`’, which is used if it exists (which it does not in a “factory-fresh” installation). This code is loaded into package base. Users need to be careful not to unintentionally overwrite objects in base, and it is normally advisable to use `local` if code needs to be executed: see the examples.

Then, unless `--no-init-file` was given, R searches for a file called ‘`.Rprofile`’ in the current directory or in the user's home directory (in that order) and sources it into the user workspace.

It then loads a saved image of the user workspace from ‘`.RData`’ if there is one (unless `--no-restore-data` was specified, or `--no-restore`, on the command line).

Next, if a function `.First` is found on the search path, it is executed as `.First()`. Finally, function `.First.sys()` in the base package is run. This calls `require` to attach the default packages specified by `options("defaultPackages")`. If the methods package is included, this will have been attached earlier, by function `.OptRequireMethods()`, so that namespace initializations such as those from the user workspace will proceed correctly.

A function `.First` (and `.Last`) can be defined in appropriate ‘`.Rprofile`’ or ‘`Rprofile.site`’ files or have been saved in ‘`.RData`’. If you want a different set of packages than the default ones when you start, insert a call to `options` in the ‘`.Rprofile`’ or ‘`Rprofile.site`’ file. For example, `options(defaultPackages = character())` will attach no extra packages on startup. Alternatively, set `R_DEFAULT_PACKAGES=NULL` as an environment variable before running R. Using `options(defaultPackages = "")` or `R_DEFAULT_PACKAGES=""` enforces the R system default.

The commands history is read from the file specified by the environment variable `R_HISTFILE` (default ‘`.Rhistory`’) unless `--no-restore-history` was specified (or `--no-restore`).

The command-line flag `--vanilla` implies `--no-site-file`, `--no-init-file`, `--no-restore` and `--no-environ`.

### Usage

    .First <- function() { ...... }

    .Rprofile <startup file>

### Details

Note that there are two sorts of files used in startup: environment files which contain lists of environment variables to be set, and profile files which contain R code.

Lines in a site or user environment file should be either comment lines starting with `#`, or lines of the form `name=value`. The latter sets the environmental variable `name` to `value`, overriding an existing value. If `value` contains an expression of the form `${foo-bar}`, the value is that of the environmental variable `foo` if that exists and is set to a non-empty value, otherwise `bar`. (If it is of the form `${foo}`, the default is `""`.) This construction can be nested, so `bar` can be of the same form (as in `${foo-${bar-blah}}`). Note that the braces are essential: `$HOME` will not be interpreted.

Leading and trailing white space in `value` are stripped. `value` is processed in a similar way to a Unix shell. In particular the outermost level of (single or double) quotes is stripped, and backslashes are removed except inside quotes.

### Note

The file ‘`$R_HOME/etc/Renviron`’ is always read very early in the start-up processing. It contains environment variables set by R in the configure process. Values in that file can be overriden in site or user environment files: do not change ‘`$R_HOME/etc/Renviron`’ itself. Note that this is distinct from ‘`$R_HOME/etc/Renviron.site`’.

### See Also

`.Last` for final actions before termination. `commandArgs` for accessing the command line arguments.

An Introduction to R for more command-line options: those affecting memory management are covered in the help file for Memory.

For profiling code, see `Rprof`.

### Examples

    ## Not run:
    # Example ~/.Renviron on Unix
    R_LIBS=~/R/library
    PAGER=/usr/local/bin/less

    # Example .Renviron on Windows
    R_LIBS=C:/R/library
    MY_TCLTK=yes
    TCL_LIBRARY=c:/packages/Tcl/lib/tcl8.4

    # Example of .Rprofile
    options(width=65, digits=5)
    options(show.signif.stars=FALSE)
    ps.options(horizontal=FALSE)
    set.seed(1234)
    .First <- function() cat("\n   Welcome to R!\n\n")
    .Last <- function()  cat("\n   Goodbye!\n\n")

    # Example of Rprofile.site
    local({
      old <- getOption("defaultPackages")
      options(defaultPackages = c(old, "MASS"))
    })

    ## if .Renviron contains
    FOOBAR="coo\bar"doh\ex"abc\"def'"

    ## then we get
    > cat(Sys.getenv("FOOBAR"), "\n")
    coo\bardoh\exabc"def'
    ## End(Not run)

[Package base version 2.4.1 Index]