Chapter 16 Appendix B Invoking R
Users of R on Windows or macOS should read the OS-specific section first, but command-line use is also supported.
B.1 Invoking R from the command line
When working at a command line on UNIX or Windows, the command ‘R’ can be used both for starting the main R program in the form
R [options] [<infile] [>outfile],
or, via the
R CMD interface, as a wrapper to various R tools (e.g., for processing files in R documentation format or manipulating add-on packages) which are not intended to be called “directly”.
At the Windows command-line,
Rterm.exe is preferred to
You need to ensure that either the environment variable
TMPDIR is unset or it points to a valid place to create temporary files and directories.
Most options control what happens at the beginning and at the end of an R session. The startup mechanism is as follows (see also the on-line help for topic ‘Startup’ for more information, and the section below for some Windows-specific details).
Unless –no-environ was given, 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, R_HOME/etc/Renviron.site is used (if it exists). The user file is the one pointed to by the environment variable
R_ENVIRON_USERif this is set; otherwise, files .Renviron in the current or in the user’s home directory (in that order) are searched for. These files should contain lines of the form ‘name=value’. (See
help(“Startup”)for a precise description.) Variables you might want to set include
R_PAPERSIZE(the default paper size),
R_PRINTCMD(the default print command) and
R_LIBS(specifies the list of R library trees searched for add-on packages).
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_PROFILEenvironment variable. If that variable is unset, the default R_HOME/etc/Rprofile.site is used if this exists.
Then, unless –no-init-file was given, R searches for a user profile and sources it. The name of this file is taken from the environment variable
R_PROFILE_USER; if unset, a file called .Rprofile in the current directory or in the user’s home directory (in that order) is searched for.
- It also loads a saved workspace from file .RData in the current directory if there is one (unless –no-restore or –no-restore-data was specified).
Finally, if a function
.First()exists, it is executed. This function (as well as
.Last()which is executed at the end of the R session) can be defined in the appropriate startup profiles, or reside in .RData.
In addition, there are options for controlling the memory available to the R process (see the on-line help for topic ‘Memory’ for more information). Users will not normally need to use these unless they are trying to limit the amount of memory used by R.
R accepts the following command-line options.
Print short help message to standard output and exit successfully.
Print version information to standard output and exit successfully.
Specify the encoding to be assumed for input from the console or
stdin. This needs to be an encoding known to
iconv: see its help page. (
–encoding encis also accepted.) The input is re-encoded to the locale R is running in and needs to be representable in the latter’s encoding (so e.g. you cannot re-encode Greek text in a French locale unless that locale uses the UTF-8 encoding).
Print the path to the R “home directory” to standard output and exit successfully. Apart from the front-end shell script and the man page, R installation puts everything (executables, packages, etc.) into this directory.
Control whether data sets should be saved or not at the end of the R session. If neither is given in an interactive session, the user is asked for the desired behavior when ending the session with q(); in non-interactive use one of these must be specified or implied by some other option (see below).
Do not read any user file to set environment variables.
Do not read the site-wide profile at startup.
Do not read the user’s profile at startup.
Control whether saved images (file .RData in the directory where R was started) should be restored at startup or not. The default is to restore. (–no-restore implies all the specific –no-restore-* options.)
Control whether the history file (normally file .Rhistory in the directory where R was started, but can be set by the environment variable
R_HISTFILE) should be restored at startup or not. The default is to restore.
(Windows only) Prevent loading the Rconsole file at startup.
Combine –no-save, –no-environ, –no-site-file, –no-init-file and –no-restore. Under Windows, this also includes –no-Rconsole.
Rgui.exe) Take input from file: ‘-’ means
stdin. Implies –no-save unless –save has been set. On a Unix-alike, shell metacharacters should be avoided in file (but spaces are allowed).
- -e expression
Rgui.exe) Use expression as an input line. One or more -e options can be used, but not together with -f or –file. Implies –no-save unless –save has been set. (There is a limit of 10,000 bytes on the total length of expressions used in this way. Expressions containing spaces or shell metacharacters will need to be quoted.)
(UNIX only) Turn off command-line editing via readline. This is useful when running R from within Emacs using the ESS (“Emacs Speaks Statistics”) package. See The command-line editor, for more information. Command-line editing is enabled for default interactive use (see –interactive). This option also affects tilde-expansion: see the help for
For expert use only: set the initial trigger sizes for garbage collection of vector heap (in bytes) and cons cells (number) respectively. Suffix ‘M’ specifies megabytes or millions of cells respectively. The defaults are 6Mb and 350k respectively and can also be set by environment variables
Specify the maximum size of the pointer protection stack as N locations. This defaults to 10000, but can be increased to allow large and complicated calculations to be done. Currently the maximum value accepted is 100000.
(Windows only) Specify a limit for the amount of memory to be used both for R objects and working areas. This is set by default to the smaller of the amount of physical RAM in the machine and for 32-bit R, 1.5Gb26, and must be between 32Mb and the maximum allowed on that version of Windows.
Do not print out the initial copyright and welcome messages.
Make R run as quietly as possible. This option is intended to support programs which use R to compute results for them. It implies –quiet and –no-save.
(UNIX only) Assert that R really is being run interactively even if input has been redirected: use if input is from a FIFO or pipe and fed from an interactive program. (The default is to deduce that R is being run interactively if and only if stdin is connected to a terminal or
pty.) Using -e, -f or –file asserts non-interactive use even if –interactive is given.
Note that this does not turn on command-line editing.
(Windows only) Set
Rtermup for use by
R-inferior-modein ESS, including asserting interactive use (without the command-line editor) and no buffering of stdout.
Print more information about progress, and in particular set R’s option
TRUE. R code uses this option to control the printing of diagnostic messages.
(UNIX only) Run R through debugger name. For most debuggers (the exceptions are
valgrindand recent versions of
gdb), further command line options are disregarded, and should instead be given when starting the R executable from inside the debugger.
(UNIX only) Use type as graphical user interface (note that this also includes interactive graphics). Currently, possible values for type are ‘X11’ (the default) and, provided that ‘Tcl/Tk’ support is available, ‘Tk’. (For back-compatibility, ‘x11’ and ‘tk’ are accepted.)
(UNIX only) Run the specified sub-architecture.
This flag does nothing except cause the rest of the command line to be skipped: this can be useful to retrieve values from it with
Note that input and output can be redirected in the usual way (using ‘<’ and ‘>’), but the line length limit of 4095 bytes still applies. Warning and error messages are sent to the error channel (
R CMD allows the invocation of various tools which are useful in conjunction with R, but not intended to be called “directly”. The general form is
R CMD command args
where command is the name of the tool and args the arguments passed on to it.
Currently, the following tools are available.
Run R in batch mode. Runs
R –restore –savewith possibly further options (see
(UNIX only) Compile C, C++, Fortran … files for use with R.
Build shared library for dynamic loading.
Install add-on packages.
Remove add-on packages.
Build (that is, package) add-on packages.
Check add-on packages.
(UNIX only) Front-end for creating executable programs.
Post-process R profiling files.
Convert Rd format to various other formats, including HTML, LaTeX, plain text, and extracting the examples.
Rd2txtcan be used as shorthand for
Rd2conv -t txt.
Convert Rd format to PDF.
Extract S/R code from Sweave or other vignette documentation
Process Sweave or other vignette documentation
Diff R output ignoring headers etc
Obtain configuration information
(Unix only) Update the Java configuration variables
(Unix only) Create Emacs-style tag files from C, R, and Rd files
(Windows only) Open a file via Windows’ file associations
(Windows only) Process (La)TeX files with R’s style files
R CMD command --help
to obtain usage information for each of the tools accessible via the
R CMD interface.
In addition, you can use options –arch=, –no-environ, –no-init-file, –no-site-file and –vanilla between
CMD: these affect any R processes run by the tools. (Here –vanilla is equivalent to –no-environ –no-site-file –no-init-file.) However, note that
R CMD does not of itself use any R startup files (in particular, neither user nor site Renviron files), and all of the R processes run by these tools (except
BATCH) use –no-restore. Most use –vanilla and so invoke no R startup files: the current exceptions are
SHLIB (which uses –no-site-file –no-init-file).
R CMD cmd args
for any other executable
cmd on the path or given by an absolute filepath: this is useful to have the same environment as R or the specific commands run under, for example to run
pdflatex. Under Windows cmd can be an executable or a batch file, or if it has extension
.pl the appropriate interpreter (if available) is called to run it.
B.2 Invoking R under Windows
There are two ways to run R under Windows. Within a terminal window (e.g.
cmd.exe or a more capable shell), the methods described in the previous section may be used, invoking by
R.exe or more directly by
Rterm.exe. For interactive use, there is a console-based GUI (
The startup procedure under Windows is very similar to that under UNIX, but references to the ‘home directory’ need to be clarified, as this is not always defined on Windows. If the environment variable
R_USER is defined, that gives the home directory. Next, if the environment variable
HOME is defined, that gives the home directory. After those two user-controllable settings, R tries to find system defined home directories. It first tries to use the Windows “personal” directory (typically
My Documents in recent versions of Windows). If that fails, and environment variables
HOMEPATH are defined (and they normally are) these define the home directory. Failing all those, the home directory is taken to be the starting directory.
You need to ensure that either the environment variables
TEMP are either unset or one of them points to a valid place to create temporary files and directories.
Environment variables can be supplied as ‘name=value’ pairs on the command line.
If there is an argument ending .RData (in any case) it is interpreted as the path to the workspace to be restored: it implies –restore and sets the working directory to the parent of the named file. (This mechanism is used for drag-and-drop and file association with
RGui.exe, but also works for
Rterm.exe. If the named file does not exist it sets the working directory if the parent directory exists.)
The following additional command-line options are available when invoking
Rguiwill operate as an MDI program (with multiple child windows within one main window) or an SDI application (with multiple top-level windows for the console, graphics and pager). The command-line setting overrides the setting in the user’s Rconsole file.
Enable the “Break to debugger” menu item in
Rgui, and trigger a break to the debugger during command line processing.
Under Windows with
R CMD you may also specify your own .bat, .exe, .sh or .pl file. It will be run under the appropriate interpreter (Perl for .pl) with several environment variables set appropriately, including
TEXINPUTS. For example, if you already have latex.exe on your path, then
R CMD latex.exe mydoc
will run LaTeX on mydoc.tex, with the path to R’s share/texmf macros appended to
TEXINPUTS. (Unfortunately, this does not help with the MiKTeX build of LaTeX, but
R CMD texify mydoc will work in that case.)
B.3 Invoking R under macOS
There are two ways to run R under macOS. Within a
Terminal.app window by invoking
R, the methods described in the first subsection apply. There is also console-based GUI (
R.app) that by default is installed in the
Applications folder on your system. It is a standard double-clickable macOS application.
The startup procedure under macOS is very similar to that under UNIX, but
R.app does not make use of command-line arguments. The ‘home directory’ is the one inside the R.framework, but the startup and current working directory are set as the user’s home directory unless a different startup directory is given in the Preferences window accessible from within the GUI.
B.4 Scripting with R
If you just want to run a file foo.R of R commands, the recommended way is to use
R CMD BATCH foo.R. If you want to run this in the background or as a batch job use OS-specific facilities to do so: for example in most shells on Unix-alike OSes
R CMD BATCH foo.R & runs a background job.
You can pass parameters to scripts via additional arguments on the command line: for example (where the exact quoting needed will depend on the shell in use)
R CMD BATCH "--args arg1 arg2" foo.R &
will pass arguments to a script which can be retrieved as a character vector by
args <- commandArgs(TRUE)
This is made simpler by the alternative front-end
Rscript, which can be invoked by
Rscript foo.R arg1 arg2
and this can also be used to write executable script files like (at least on Unix-alikes, and in some Windows shells)
#! /path/to/Rscript args <- commandArgs(TRUE) ... q(status=<exit status code>)
If this is entered into a text file runfoo and this is made executable (by
chmod 755 runfoo), it can be invoked for different arguments by
runfoo arg1 arg2
For further options see
help(“Rscript”). This writes R output to stdout and stderr, and this can be redirected in the usual way for the shell running the command.
If you do not wish to hardcode the path to
Rscript but have it in your path (which is normally the case for an installed R except on Windows, but e.g. macOS users may need to add /usr/local/bin to their path), use
#! /usr/bin/env Rscript ...
At least in Bourne and bash shells, the
#! mechanism does not allow extra arguments like
#! /usr/bin/env Rscript –vanilla.
One thing to consider is what
stdin() refers to. It is commonplace to write R scripts with segments like
chem <- scan(n=24) 2.90 3.10 3.40 3.40 3.70 3.70 2.80 2.50 2.40 2.40 2.70 2.20 5.28 3.37 3.03 3.03 28.95 3.77 3.40 2.20 3.50 3.60 3.70 3.70
stdin() refers to the script file to allow such traditional usage. If you want to refer to the process’s stdin, use
“stdin” as a
file connection, e.g.
Another way to write executable script files (suggested by François Pinard) is to use a here document like
#!/bin/sh [environment variables can be set here] R --slave [other options] <<EOF R program goes here... EOF
stdin() refers to the program source and
“stdin” will not be usable.
Short scripts can be passed to
Rscript on the command-line via the -e flag. (Empty scripts are not accepted.)
Note that on a Unix-alike the input filename (such as foo.R) should not contain spaces nor shell metacharacters.