this.path (version 0.4.4)

Running.R.from.the.command-line: Running R from the Windows Command-line / / Unix Terminal

Description

How to run R from the Windows command-line / / Unix terminal.

Difference Between R Executables

For running R scripts, I recommended the ‘Rterm’ executable. Here are how the other executables can also be used to run R scripts, and what makes them different.

The ‘R’ executable can be used to call the ‘Rcmd’ or ‘Rterm’ executable. It does not provide any additional functionality that the ‘Rcmd’ and ‘Rterm’ executables do not already have, so it is unnecessary to call this executable directly.

The ‘Rcmd’ executable is mainly used for preparing R packages. The only command that that isn't for R packages specifically is Rcmd BATCH ... which is used for running R scripts. However, this command directly calls the ‘Rterm’ executable. The difference is that the ‘Rcmd’ executable always produces an output file (containing stdout and stderr) and always uses the options --restore and --save. Depending on the setting, you may want an output file and to use those two options, but since the choice is not given, the ‘Rterm’ executable is preferable. Since the ‘Rcmd’ executable directly calls the ‘Rterm’ executable, it means that the ‘Rcmd’ executable does not provide any additional functionality.

The ‘Rscript’ executable directly calls the ‘Rterm’ executable. The difference is that the ‘Rscript’ executable has different syntax for providing the filename of the input script and always uses the options --no-echo and --no-restore. Since the choice is not given, the ‘Rterm’ executable is again preferable. The ‘Rscript’ executable does not provide any additional functionality.

The ‘Rterm’ executable has a few advantages. The syntax is more consistent for providing an input file. The syntax is better for providing the filename in which to place output. No options are forced. And environment variables can be provided in the command.

Ease of Use on Windows

On a Unix-alike OS (including macOS), it is easy to invoke an R session from the terminal by simply typing the name of the R executable file you wish to run. On Windows, you should see that typing the name of the executable file you wish to run does not run that application, but instead throws an error. Instead, you will have to type the full path of the directory where your R executable files are located (see section Where are my R executable files located?), followed by the name of the R executable file you wish to run.

This is not very convenient to type everytime something needs to be run from the command-line, plus it has another issue of being computer dependent. The solution is to add the path of the directory where your R executable files are located to the Path environment variable. The Path environment variable is a list of directories where executable programs are located. When you type the name of an executable program you wish to run, Windows looks for that program through each directory in the Path environment variable. When you add the full path of the directory where your R executable files are located to your Path environment variable, you should be able to run any of those executable programs by their basenames (‘R’, ‘Rcmd’, ‘Rscript’, and ‘Rterm’) instead of their full paths.

To add a new path to your Path environment variable, first open the Control Panel. You should be able to do this by pressing Windows, Windows+R, or opening a file explorer window and then typing Control Panel in the prompt. From there, open the category System and Security, then open the category System, then open Advanced system settings (should appear near the top left), then open Environment Variables... (should appear near the bottom right). You should see a new window split in two sections, environment variables for the current user and environment variables for the system. If all users of this machine are using the same R executable files, you can add the path to the system environment variables (this is what I did), otherwise you can add it to your user environment variables. Click the variable Path, then click Edit..., then click New, then type (or paste) the full path of the directory where your R executable files are located.

To check that this worked correctly, open the command-line and execute the following commands:

Rterm --help

Rterm --version

You should see that the first prints the usage message for the ‘Rterm’ executable file while the second prints information about the version of R currently being run. Make sure this is the version of R you wish to run.

Where are my R executable files located?

In an R session, you can find the location of your R executable files with the following command:

cat(sQuote(normalizePath(R.home(component = "bin"))))

For me, this is:

C:\Program Files\R\R-4.0.2\bin\x64

Details

When you download R, you are given four executable files that can be used from the command-line / / terminal. These are ‘R’, ‘Rcmd’, ‘Rscript’, and ‘Rterm’. For the purposes of running R scripts, only ‘Rterm’ is needed. Explanations for the other executables can be found in sections Difference Between R Executables and Examples.

Suppose you wanted to run an R script with a filename ‘input R script’ from the command-line / / terminal. You would write and execute one of the following commands:

Rterm -f "input R script"

Rterm --file="input R script"

this.path is capable of recognizing either of these, so use whichever you prefer.

There are plenty of other options that ‘Rterm’ accepts, you can find all of them by executing the following command:

Rterm --help

The few I use the most are:

-q do not print the R startup message (equivalent to --quiet and --silent)

--no-echo make R run as quietly as possible (includes -q)

--verbose print information about progress (includes setting option “verbose” to TRUE)

--args indicates that arguments following this argument are for the R script itself, which can be accessed in your script with the following command: commandArgs(trailingOnly = TRUE)

If, when you execute one of the previous commands, you see the following error message: “‘Rterm’ is not recognized as an internal or external command, operable program or batch file.”, see section Ease of Use on Windows.

Examples

# NOT RUN {
tryCatch({


    ## the following shows that 'Rscript' is just a wrapper for 'Rterm' with a few
    ## extra options. This makes 'Rscript' less desirable in my opinion.


    cat("\n* first, from 'Rterm'\n")
    invisible(system("Rterm   -e \"commandArgs()\"")
    )  # "Rterm" "-e" "commandArgs()"


    cat("\n* next, from 'Rscript'\n\n")
    invisible(system("Rscript -e \"commandArgs()\"")
    )  # "Rterm" "--no-echo" "--no-restore" "-e" "commandArgs()"
}, condition = function(c) cat(conditionMessage(c)))


tryCatch((function() {
    on.exit(suppressWarnings(file.remove(tmp.R.script, outfile)))


    ## the following shows that 'Rcmd BATCH' is just a wrapper for 'Rterm' with a
    ## few extra options. It also show that 'Rcmd BATCH' always creates an output
    ## file, making 'Rcmd BATCH' less desirable in my opinion.


    tmp.R.script <- tempfile(fileext = ".R")
    writeLines("commandArgs()", tmp.R.script)
    invisible(system(sprintf("Rcmd BATCH %s",
        this.path:::file.encode(tmp.R.script))))
    outfile <- paste0(sub("\\.R$", "", tmp.R.script), ".Rout")
    outfile.lines <- readLines(outfile)
    outfile.lines <- outfile.lines[-1:-which(outfile.lines == "> commandArgs()")[[1L]]]
    outfile.lines <- outfile.lines[-which(outfile.lines == "> "):-length(outfile.lines)]


    cat("\n* first, from 'Rterm'\n")
    invisible(system(sprintf("Rterm -f %s",
        this.path:::file.encode(tmp.R.script))))


    cat("\n* next, from 'Rcmd BATCH'\n\n")
    cat(outfile.lines, sep = "\n")
})(), condition = function(c) cat(conditionMessage(c)))
# }