Initialization at Start of an R Session

Description

InR, the startup mechanism is as follows.

Unless--no-environ was given on the command line,Rsearches for site and user files to process for setting environmentvariables. The name of the site file is the one pointed to by theenvironment variableR_ENVIRON; if this is unset,‘R_HOME/etc/Renviron.site’ is used (if it exists,which it does not in a ‘factory-fresh’ installation). The nameof the user file can be specified by theR_ENVIRON_USERenvironment variable; if this is unset, the files searched for are‘.Renviron’ in the current or in the user's home directory (inthat order). See ‘Details’ for how the files are read.

ThenR searches for the site-wide startup profile file ofR codeunless the command line option--no-site-file was given. Thepath of this file is taken from the value of theR_PROFILEenvironment variable (after tilde expansion). If this variableis 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 sourced into thebase package. Users need to becareful not to unintentionally overwrite objects inbase, and itis normally advisable to uselocal if code needs to beexecuted: see the examples.

Then, unless--no-init-file was given,R searches for a userprofile, a file ofR code. The path of this file can be specified bytheR_PROFILE_USER environment variable (andtilde expansion will be performed). If this is unset, a filecalled ‘.Rprofile’ is searched for in the current directory or inthe user's home directory (in that order). The user profile file issourced into the workspace.

Note that when the site and user profile files are sourced only thebase package is loaded, so objects in other packages need to bereferred to by e.g.utils::dump.frames or after explicitlyloading the package concerned.

R then loads a saved image of the user workspace from ‘.RData’in the current directory if there is one (unless--no-restore-data or--no-restore was specified onthe command line).

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

A function.First (and.Last) can be defined inappropriate ‘.Rprofile’ or ‘Rprofile.site’ files or havebeen saved in ‘.RData’. If you want a different set of packagesthan the default ones when you start, insert a call tooptions in the ‘.Rprofile’ or ‘Rprofile.site’file. For example,options(defaultPackages = character()) willattach no extra packages on startup (only thebase package) (orsetR_DEFAULT_PACKAGES=NULL as an environment variable beforerunningR). Usingoptions(defaultPackages = "") orR_DEFAULT_PACKAGES="" enforces the Rsystem default.

On front-ends which support it, the commands history is read from thefile specified by the environment variableR_HISTFILE (default‘.Rhistory’ in the current directory) unless--no-restore-history or--no-restore was specified.

The command-line option--vanilla implies--no-site-file,--no-init-file,--no-environ and (except forR CMD)--no-restore

Details

Note that there are two sorts of files used in startup:environment files which contain lists of environment variablesto be set, andprofile files which containR code.

Lines in a site or user environment file should be either commentlines starting with#, or lines of the formname=value. The latter sets the environmentalvariablename tovalue, overriding anexisting value. Ifvalue contains an expression of theform${foo-bar}, the value is that of the environmentalvariablefoo if that is set, otherwisebar. For${foo:-bar}, the value is that offoo if that is set toa non-empty value, otherwisebar. (If it is of the form${foo}, the default is"".) This construction can benested, sobar can be of the same form (as in${foo-${bar-blah}}). Note that the braces are essential: forexample$HOME will not be interpreted.

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

On systems with sub-architectures (mainly Windows), thefiles ‘Renviron.site’ and ‘Rprofile.site’ are looked forfirst in architecture-specific directories,e.g. ‘R_HOME/etc/i386/Renviron.site’.And e.g. ‘.Renviron.i386’ will be used in preferenceto ‘.Renviron’.

There is a 100,000 byte limit on the length of a line (after expansions)in environment files (prior toR 4.1 it was 10,000).

Note

It is not intended that there be interaction with the user duringstartup code. Attempting to do so can crash theR process.

On Unix versions ofR there is also a file‘R_HOME/etc/Renviron’ which is read very early inthe start-up processing. It contains environment variables set byRin the configure process. Values in that file can be overridden insite or user environment files: do not change‘R_HOME/etc/Renviron’ itself. Note that this isdistinct from ‘R_HOME/etc/Renviron.site’.

Command-line options may well not apply to alternative front-ends:they do not apply toR.app on macOS.

R CMD check andR CMD build do not always read thestandard startup files, but they do always read specificRenviron files. The location of these can be controlled by theenvironment variablesR_CHECK_ENVIRON andR_BUILD_ENVIRON.If these are set their value is used as the path for theRenviron file; otherwise, files ‘~/.R/check.Renviron’ or‘~/.R/build.Renviron’ or sub-architecture-specific versions areemployed.

If you want ‘~/.Renviron’ or ‘~/.Rprofile’ to be ignored bychildR processes (such as those run byR CMD check andR CMD build), set the appropriate environment variableR_ENVIRON_USER orR_PROFILE_USER to (if possible, which itis not on Windows)"" or to the name of a non-existent file.

Prior toR 4.0.0,${foo-bar} in an environment file skipped anemptyfoo: this has been changed to match the POSIX rules forparameter substitution in shells.

See Also

For the definition of the ‘home’ directory on Windows see the‘rw-FAQ’ Q2.14. It can be found from a runningR bySys.getenv("R_USER").

.Last for final actions at the close of anR session.commandArgs for accessing the command line arguments.

There are examples of using startup files to set defaults for graphicsdevices in the help forX11 andquartz.

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

readRenviron to read ‘.Renviron’ files.

For profiling code, seeRprof.

Examples

## Not run: ## Example ~/.Renviron on UnixR_LIBS=~/R/libraryPAGER=/usr/local/bin/less## Example .Renviron on WindowsR_LIBS=C:/R/libraryMY_TCLTK="c:/Program Files/Tcl/bin"## Example of setting R_DEFAULT_PACKAGES (from R CMD check)R_DEFAULT_PACKAGES='utils,grDevices,graphics,stats'# this loads the packages in the order given, so they appear on# the search path in reverse order.## Example of .Rprofileoptions(width=65, digits=5)options(show.signif.stars=FALSE)setHook(packageEvent("grDevices", "onLoad"),        function(...) grDevices::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.sitelocal({  # add MASS to the default packages, set a CRAN mirror  old <- getOption("defaultPackages"); r <- getOption("repos")  r["CRAN"] <- "http://my.local.cran"  options(defaultPackages = c(old, "MASS"), repos = r)  ## (for Unix terminal users) set the width from COLUMNS if set  cols <- Sys.getenv("COLUMNS")  if(nzchar(cols)) options(width = as.integer(cols))  # interactive sessions get a fortune cookie (needs fortunes package)  if (interactive())    fortunes::fortune()})## if .Renviron containsFOOBAR="coo\bar"doh\ex"abc\"def'"## then we get# > cat(Sys.getenv("FOOBAR"), "\n")# coo\bardoh\exabc"def'## End(Not run)