Getting Started

The CRAN macOS page offers two installers for 4.6.1: R-4.6.1-arm64.pkg for Apple silicon Macs (macOS 14 or later) and R-4.6.1-x86_64.pkg for Intel Macs (macOS 11 or later). Both are signed and notarized Apple Installer packages; double-click the file you downloaded (download to the desktop or your home folder rather than the Downloads folder, which the installer may not be allowed to read) and follow the steps. The installer offers four components; everyone needs the "R Framework", and the Tcl/Tk and Texinfo components are optional (Tcl/Tk is needed by the tcltk package, Texinfo only when installing source packages or R from source). The CRAN page shows how to check the download:

Source: R for macOS (CRAN)

Three details from "R Installation and Administration" and the R for macOS FAQ are worth knowing. First, R.app (the GUI console in /Applications) and the command-line R and Rscript both come from the same installation. Second, the X11 graphics device and the tcltk package need XQuartz. Third, the installer replaces the previous version with the same x.y series, and different series live side by side under /Library/Frameworks/R.framework/Versions (such as 4.6 and 4.5-arm64), with R.app always running the last one installed, so 4.6.0 and 4.6.1 cannot coexist but 4.5 and 4.6 can.

Source: R-admin, 4 Installing R under macOS

Source: R for macOS FAQ, 1.3 How can R for macOS be obtained and installed?

Download R-4.6.1-win.exe from the "R for Windows" page, double-click it and follow the instructions; you choose a language for the installer, which applies to installation and uninstallation but not to running R. 64-bit R for Windows 10 and later is the supported build (R 4.1 was the last release with a 32-bit build), it uses the Universal C Runtime that ships with Windows 10 and Windows Server 2016 and later, and from R 4.2.0 it uses UTF-8 as its native encoding where Windows supports it. Rgui.exe is the graphical console and Rterm.exe the terminal one; people who run R from a terminal usually prefer Rterm.exe. The installer does not put R on the PATH by default, so R and Rscript typed into a Command Prompt work only after you add the bin directory of the installation to the PATH or give the full path. R can be uninstalled from the Control Panel, and uninstalling removes only the files of the initial installation, not the packages you added.

Source: R for Windows (CRAN)

Source: R-admin, 3 Installing R under Windows

Source: R for Windows FAQ, 2.2 How do I install R for Windows?

Distribution packages are the simplest route, with the caveat that a distribution’s R can be older than the current release; the commands below install the R that the distribution offers, and the CRAN pages say how to get newer builds.

On Debian the base R system has been packaged since 1997. r-base installs R and the recommended packages, and r-base-dev is needed only if you compile packages from source:

Source: Debian packages of R software (CRAN)

On Ubuntu, CRAN publishes its own apt repository for the supported long-term-support releases. The "Ubuntu Packages For R" page says to add the signing key and the repository (lsb_release -cs picks the release name, and the suffix -cran40 marks the binary compatibility break of R 4.0 and still installs the current 4.6 series), then install r-base:

Source: Ubuntu packages for R (CRAN)

On Fedora, the R package is a meta-package that pulls in R-core (the runtime), R-core-devel (the files needed to build packages), the Java variants and the standalone math library; installing the meta-package is the recommended route, because most users need all of the components. CentOS and RHEL get the same RPMs from EPEL.

Source: Fedora packages of R software (CRAN)

After installing from any of them, R --version should print the version you expect; if it prints an older one, the distribution’s repository is behind CRAN.

Building from source is covered by chapter 2 of "R Installation and Administration": unpack R-x.y.z.tar.gz, run ./configure and make, and optionally make install. The R FAQ adds that you need a Fortran compiler as well as a C compiler. Daily snapshots of R-patched and R-devel are available from CRAN as well, and the manual notes that they are built exactly like releases. Most readers never need this route; it matters for testing against R-devel and for unusual platforms.

Source: R-admin, 2 Installing R under Unix-alikes

Source: R FAQ, 2.5.1 How can R be installed (Unix-like)

A machine that needs more than one R (a stable one for work and the newest for testing) can use rig, the R Installation Manager. It is a community tool, not part of R and not maintained by R Core: it is published under the r-lib organisation on GitHub with the MIT licence (version 0.11.0 at the time of writing), and its README describes it as installing several R versions side by side, selecting them by symbolic names such as release, devel and oldrel or by exact version, and switching the default for the terminal and for the RStudio and Positron IDEs. It works on macOS, Windows and Linux, and on Windows it also installs and configures the matching Rtools. The README’s quick start is three commands:

Source: rig README (r-lib/rig)

Nothing in this section depends on rig; the official installers above are enough. It is mentioned because "which R am I running?" is a common source of confusion when several are installed, and Which R Is This? shows how to answer it from inside R.

A binary package needs no tools to install, and that is what install.packages() fetches by default on Windows and macOS. Compilers matter only for source packages that contain C, C++ or Fortran code, which "R Installation and Administration" says need compilers and related tools to be installed, and for building R itself.

Source: R-admin, C.3 macOS (platform notes)

Source: Rtools: toolchains for building R and R packages from source on Windows (CRAN)

Source: Rtools45 for Windows (CRAN)

The command-line tools example is a one-line shell command, not R code. Whether the tools are needed for a particular package is decided when you install it: the console prints the compiler error and the package page on CRAN lists the system requirements. The detail belongs on Packages, Libraries and Namespaces.

R --version and Rscript --version print the version banner and exit. The R banner continues with the platform line and the licence text, which are shortened here:

Source: R-intro, B.1 Invoking R from the command line

The text between the quotation marks on the first line, "Happy Hop", is the release nickname (see Release Cycle and Version Numbers).

Typing R in a terminal (or opening R.app, Rgui, or an IDE’s console) starts an interactive session: R prints a banner and then the prompt >, which means that it is waiting for a complete command. "An Introduction to R" suggests creating a separate directory for each piece of work and starting R from it, because the working directory is where R looks for files and where it saves the workspace.

When what you typed is not yet a complete expression, R shows the continuation prompt + and waits for more. The usual causes are an open parenthesis or brace, an unfinished string, or an operator at the end of a line:

Source: R-intro, 1.5 Using R interactively

This is a console transcript: the prompts are printed by the interactive console and are not part of the code, which is why every other example on this page leaves them out and shows printed output as #> comments. (If you copy a transcript into a script with the > prompts included, R stops with Error: unexpected '>' in ">".)

The same prompt appears when a quote is left open, and then the prompt stays: everything you type is part of the string. The transcript below was produced by typing the lines into R in a terminal; the last step, pressing Ctrl-C, abandons the unfinished command and returns the > prompt:

Source: R for macOS FAQ, 10.3 How can I interrupt lengthy operations or output?

To interrupt a command that is waiting for input or a long computation, press Esc in R.app, RStudio and Positron, or Ctrl-C in a terminal (the macOS FAQ states both). The command line also has a readline-style editor: the up and down arrows recall earlier commands, and Ctrl-A and Ctrl-E move to the start and end of the line (the readline library must have been available when R was built; the R FAQ names libreadline-dev on Debian and readline-devel on Red Hat as the packages to install before compiling).

At the console every expression you type is evaluated and its value is printed, unless the value is invisible. The value of an assignment is invisible, which is why x <- 42 prints nothing and x prints [1] 42, and parentheses make it visible again. invisible() returns its argument without printing it at the top level, which is how functions such as print() return the object they just printed. The next script, run with Rscript, shows each case; Rscript autoprints top-level expressions exactly like the console, only without echoing the code or the prompts:

Source: R documentation: invisible

Read the output line by line against the script. 1 + 1 prints [1] 2; x <- 42 prints nothing, x prints [1] 42 and (y <- 7) prints [1] 7; invisible(5) and quiet() print nothing, print(quiet()) and v do. The two loops show that a loop returns NULL invisibly: for (i in 1:2) i produces no output at all, and only the explicit print(i) does, so inside loops and functions (as in files read by source(), see source() Prints Nothing) you must call print() yourself. The bracketed number at the start of each output line, [1] or [26], is the position, within the vector, of the first element on that line; the last example is a vector of 30 numbers wrapped at the console width.

Source: R documentation: print

Source: R documentation: Control (for loops)

q() (the same function as quit()) ends the session. In an interactive terminal R then asks whether to save the workspace, the set of objects you created:

Source: R documentation: quit

The answers are y (write the objects to a file called .RData and the command history to .Rhistory in the working directory, both of which are loaded again the next time R starts there), n (quit without saving) and c (cancel and stay). This is a console transcript from the terminal version; the R.app and IDE consoles show a dialog instead, and the prompt could not be reproduced from a script. The save argument sets the answer in advance (q(save = "no")), and status sets the exit code that a script returns to the operating system (q(status = 1) for a failure).

Saving the workspace is rarely what you want. It makes the next session depend on objects that are no longer visible in any script, which is the opposite of reproducible. "An Introduction to R" recommends a separate working directory per analysis for exactly this reason, because names such as x and y are meaningful only within one analysis. The R FAQ explains the mechanics: save.image() saves the global environment to .RData in the startup directory (what q("yes") also does), and rm(list = ls(all.names = TRUE)) removes every object, including those whose names start with a dot. When R is started with --vanilla, or run through Rscript, no saved workspace is restored and none is saved (--no-save alone only stops saving). How .RData, .Rprofile, .Renviron and the working directory interact is the subject of Sessions, Workspaces and Startup.

Source: R-intro, 1.11 Data permanency and removing objects

Source: R FAQ, 7.2 How can I save my workspace?

Four ways to ask, from shortest to most complete:

Source: R documentation: R.version

Two details deserve attention. R.version$minor is "6.1", a string that includes the patch level, so R.version$minor is not the minor version number; getRversion()$minor (the number 6) and getRversion()$patchlevel (1) are. And version comparisons must use version objects: getRversion() >= "4.1.0" compares component by component, while a string comparison would order "4.10.0" before "4.6.1". The R.version[...] call shows only part of the list; the full R.version also prints platform, arch, os, system, status and svn rev, which are omitted here because they identify the machine.

Source: R documentation: numeric_version

sessionInfo() prints a longer report. Its first lines name R, the platform and the operating system, then come the BLAS and LAPACK libraries, the locale and the time zone, and finally the attached base packages and the namespaces loaded without being attached. The listing below is shortened (the dots stand for the platform, library and locale lines that depend on the machine), and the attached base packages line is the one printed by a plain session:

Source: R documentation: sessionInfo

This block is a fragment, not a script: the dots are not R code.

The next file, shelf-report.R, reads a CSV file given on the command line and prints three numbers. commandArgs(trailingOnly = TRUE) returns the arguments that follow the script name as a character vector, so the script takes the file (default books.csv) and an optional minimum year; a missing file ends the run with a non-zero exit status.

Source: R documentation: commandArgs

Run it from the directory that holds books.csv. The output of each run is shown after the command; the echo $? lines print the exit status that quit(status = 2L) set.

Source: R documentation: Rscript

The script uses three idioms worth noticing. cat() prints text without the [1] prefix and without quotes, which is the usual way to write a report; message() writes to standard error, the right place for a diagnostic, so it does not mix with the report on standard output; and quit(status = ...) returns a number to the shell, which is how a script tells make, a scheduler or a continuous-integration job that it failed. The help page of quit() adds that the default error handler of a non-interactive run already exits with status 1 and that status 2 is used by R itself for catastrophic failures, so it recommends statuses of 10 or more for your own codes; the script above uses 2 only to keep the transcript short.

A few other things about Rscript, from its help page and from Rscript --help:

Source: R documentation: Rscript

On macOS and Linux a script can be made executable. "An Introduction to R" recommends #!/usr/bin/env Rscript as the first line when Rscript is on the PATH, with the note that the #! mechanism does not allow extra arguments (#!/usr/bin/env Rscript --vanilla does not work). The file below was created and run in a container with R 4.6.1:

Source: R-intro, B.4 Scripting with R

On Windows, Rscript.exe is run explicitly (or through the file association that rig system script-assoc can create), because the #! line is not used by the Command Prompt.

R --vanilla starts the normal console but combines --no-save, --no-environ, --no-site-file, --no-init-file and --no-restore (and on Windows --no-Rconsole): no environment files, no profiles, no saved workspace. It is the first thing to try when R behaves strangely, because it separates a problem in R from one in your startup files. Related options are --quiet (no banner), -e and -f/--file. R CMD BATCH foo.R is the older batch interface: it runs the file non-interactively and writes the commands and their output to foo.Rout, which ends with a proc.time() timing line. The R for Windows FAQ answers "Can I use R CMD BATCH?" with yes, and shows the equivalent Rterm.exe --no-restore --no-save < file > file.out 2>&1. New scripts are normally written for Rscript.

Source: R-intro, B.1 Invoking R from the command line

Unlike Rscript -e, R -e echoes the prompt and the expression, as the transcript shows. The value printed, "@CRAN@", is the factory setting that means "no mirror chosen yet" and leads to the next section.

A common surprise is that code which prints at the console prints nothing when read with source(). The R FAQ (7.16) explains that the returned value of a top-level expression is printed automatically at the command line and under Rscript, "but in other circumstances", such as in a file read with source(), it is not, and that you must call print() or use source(file, echo = TRUE). The script writes a three-line file and reads it three ways:

Source: R FAQ, 7.16 Why is the output not printed when I source() a file?

Source: R documentation: source

With plain source() only the explicit print(x + 1) produces output; echo = TRUE shows the code and the values, and print.eval = TRUE shows the values only. Running the same three-line file as Rscript tiny.R prints [1] 42 and [1] 43 (x autoprints), so a script run from the shell and the same script run through source() can behave differently.

Source: R documentation: library

Either the name is misspelled (package names are case-sensitive) or the package has to be installed first with install.packages(). require() is the variant that returns FALSE with a warning instead of an error, which is meant for code that decides what to do when a package is missing:

Source: R documentation: library and require

Source: R-lang, 3.1.2 Symbol lookup

R is case-sensitive: Books is not books and Library is not library. An object not found error means that no variable of that name exists in the places R looks: you forgot to run the line that creates it, you made a typo, the object was created in a script you did not run, or the workspace was cleared. A could not find function error means the same for functions, and its most frequent cause is a function from a package that has not been loaded with library().

Source: R-lang, 10 Parser

unexpected symbol and unexpected numeric constant mean that two things that should be separated by an operator or a comma are next to each other (here a missing comma or operator). unexpected '}' and unexpected ')' mean a bracket without a partner. unexpected input is typically text copied from a word processor or a web page: the curly quotes “ and ” are not the straight double quote ". The message shows the text up to the point where the parser gave up, which is where to look. A frequent special case is a line that starts with else at the top level, as in this file:

Source: R documentation: Control

Run as a script it prints [1] "positive" and then Error: unexpected 'else' in "else": R reads the file expression by expression, and the closing brace on its own line ends the if statement, so the following else starts a new, invalid one. Writing } else { on one line fixes it (inside a function body or any block in braces the problem does not occur, but a top-level layout like this one fails). This block is a deliberately wrong fragment, not a runnable script. The grammar is on Syntax and Lexical Structure.

The same family of errors is behind the stuck + prompt shown in Starting R, the Prompt and Continuation Lines: R is waiting for the rest of an unfinished expression. Use Esc or Ctrl-C to get out, check for the missing quote or bracket, and enter the command again.

Source: R documentation: Arithmetic

Source: R documentation: Extract

Source: R documentation: numeric and as.numeric

Source: R documentation: Control (if)

non-numeric argument to binary operator appears when arithmetic is attempted on text (often a column that was read as chr). subscript out of bounds is the error of [[ for a position that does not exist, whereas single-bracket indexing past the end quietly returns NA, which is why such bugs travel far before they show. NAs introduced by coercion is a warning, not an error: the command finished and returned NA, and the warning says that some values could not be converted. The last message is an error since R 4.2.0: an if condition of length greater than one is no longer a warning with the first element used (see Where Older Tutorials Differ).

Source: R documentation: getwd and setwd

The relative path "books.csv" is resolved against the working directory, which is the directory R was started in (or the one set in the IDE or shortcut). Start R from the folder that holds the file, or give the path, and check with getwd() and list.files(). Note the order of the message: the error is the generic cannot open the connection, and the cause, No such file or directory, is in the warning that follows it. The Calls: line is the call stack that led to the error, and it is a useful clue when the failing line is inside a function. So the first thing to check is the path and the working directory, not the call to read.csv().

Windows paths bring one more trap. In R strings the backslash is an escape character, so "C:\data\books.csv" is not the path you meant:

Source: R FAQ, 7.8 How do file names work in Windows?

The R FAQ gives two fixes: double every backslash ("C:\\data\\books.csv") or use forward slashes, which Windows accepts ("C:/data/books.csv"). file.path() builds a path from parts. The script prints each form:

Source: R documentation: file.path

The printed string C:\data\books.csv has 17 characters and one backslash per separator; the doubled backslash in the source is how a single backslash is written, which is why "C:\\data" has nchar 7 and not 8. (FAQ 7.37 covers backslashes inside strings in general.)