Getting started in admin mode

In admin mode R goes into the platform’s usual system-wide location, and the R and Rscript commands land in a directory that is already on everyone’s PATH. Operations that write to those places typically need admin privileges, and rig asks for your password when needed. Choose this on your own laptop, or on a server you administer.

This is rig’s default mode, and the one with the most mileage on it, so it is also the best tested. If you cannot use an administrator account, or would rather not touch system directories, follow Getting started in user mode instead. See Admin mode vs user mode for the trade-offs.

0. Before you start

Install rig first. Check that rig works and see where it puts things:

rig --version
rig system dirs

Mode          admin
Architecture  arm64
R root        /Library/Frameworks/R.framework/Versions
Binary dir    /usr/local/bin
...

rig system dirs works before any R version is installed, so it is the quickest way to confirm which mode you are in and where R will land. The directories depend on your platform, so your output will differ.

Now choose your platform to continue.

macOS

1. Install the latest release

rig add release

Because admin mode installs into /Library/Frameworks/R.framework, rig needs administrator rights, and asks for your password:

Running `sudo` for adding new R versions. This might need your password.

Besides unpacking R, rig add also configures the CRAN repository, installs pak for installing packages, sets R up to use a user package library, creates the quick links, and (if this is your first R version) makes the newly installed version the default.

2. See what you have

rig list

* name   version  aliases
-------------------------
* 4.6.1           release

The * marks the default version. rig list --plain prints just the names, one per line, which is handy in shell scripts.

3. Add a second version

R versions can be named with a version spec, not just a version number:

rig add 4.4.3      # an exact version
rig add 4.4        # the latest patch release of 4.4.x
rig add oldrel     # the previous minor release
rig add oldrel/2   # two minor releases back
rig add devel      # the current development version of R
rig add next       # the current R patched / release candidate

rig available lists everything you can install.

Note

In admin mode on macOS you cannot have two patch releases of the same minor version at once. Installing R 4.6.1 removes R 4.6.0, because they share a directory in the R framework. Adding versions from different minor branches (release and oldrel, say) is fine. User mode does not have this restriction.

4. Switch the default version

rig default          # print the current default
rig default 4.5.3    # set it

The default version is the one the plain R and Rscript commands start. rig also creates versioned quick links, so you can always reach a specific version without switching:

R                              # the default version
R-4.5.3                        # a specific version
Rscript -e 'R.version.string'  # the default version, non-interactively

In admin mode rig default works without sudo as long as your account is in the admin group.

5. Install an R package

rig add installs pak by default, so you can install R packages straight away:

R -q -e 'pak::pkg_install("dplyr")'

Packages go into a per-user, per-version library that rig configured R to create automatically, so you do not need sudo to install packages even in admin mode, and packages for different R versions never collide. On macOS rig also restricts the permissions of the system library, so you cannot install packages into it by accident.

If you want more than one library for the same R version, e.g. one per project, see the rig library command.

6. Run R without switching the default

Another way to run a specific version without changing the default is rig run. rig run runs R, a script or a whole project with any installed version, leaving your default alone:

rig run                            # start R
rig run -f analysis.R              # run a script
rig run -e 'sessionInfo()'         # evaluate an expression
rig run -r 4.5.3 -f analysis.R     # ... with a specific R version
rig run --cmd check --no-manual .  # run `R CMD check`

rig run also works if R is not on your PATH, but rig is.

7. Turn on shell completions

rig ships completions for bash, zsh, fish and elvish. See Installing auto-complete for the setup, which depends on how you installed rig.

8. macOS extras

• The menu bar app shows your R versions in the macOS menu bar and lets you switch the default with a click. It comes with the system installer and brew install r-rig-app. Start it once from Finder or with open -a Rig, then tick “Launch at login”.
• To debug R with lldb or gdb, run rig system allow-debugger. The CRAN builds are hardened against debuggers by default. There is also rig system allow-debugger-rstudio for RStudio’s rsession, and rig system allow-core-dumps.

Windows

1. Install the latest release

rig add release

Admin mode installs into C:\Program Files\R, so rig needs your password.

Besides unpacking R, rig add also configures the CRAN and P3M repositories, installs pak, sets R up to use a user package library, creates the quick links, and (if this is your first R version) makes it the default.

On arm64 Windows rig installs arm64 R builds by default. Use the --arch x86_64 flag to install an x86_64 R build. You can mix x86_64 and arm64 builds of R and Rtools.

2. See what you have

rig list

* name   version  aliases
-------------------------
* 4.6.1           release

The * marks the default version. rig list --plain prints just the names, one per line, which is handy in scripts.

3. Add a second version

R versions are named with a version spec, not just a number:

rig add oldrel     # the previous minor release
rig add 4.4.3      # an exact version
rig add 4.4        # the latest patch release of 4.4.x
rig add oldrel/2   # two minor releases back
rig add devel      # the current R-devel
rig add next       # the current R patched / release candidate

rig available lists everything you can install.

4. Switch the default version

rig default          # print the current default
rig default 4.5.3    # set it

The default version is the one the plain R and Rscript commands start. rig also creates versioned quick links, so you can always reach a specific version without switching:

R                                # the default version
R-4.5.3                          # a specific version
Rscript -e 'R.version.string'    # the default version, non-interactively

Note

If typing R in PowerShell re-runs your previous command instead of starting R, you have hit PowerShell’s built-in r alias for Invoke-History, which takes precedence over external commands. Run rig system fix-r-alias once and open a new PowerShell session.

5. Install a package

rig add installed pak, so you can install packages straight away:

R -q -e 'pak::pkg_install("dplyr")'

Packages go into a per-user, per-version library that rig configured R to create automatically, so installing packages never needs administrator rights, and packages for different R versions never collide.

If you want more than one library for the same R version (say one per project), see the rig library command.

6. Install Rtools

To build packages from source you need Rtools, which rig manages too:

rig rtools list        # what is installed
rig add rtools         # the Rtools version matching your default R
rig rtools add 45      # a specific Rtools version

rig configures R and Rtools to work without putting Rtools on the PATH, so R CMD config, R CMD sh, R CMD make and rig run --cmd config work out of the box.

7. Run R without switching the default

rig run runs R, a script or a whole project with any installed version, leaving your default alone:

rig run                            # start R
rig run -f analysis.R              # run a script
rig run -e 'sessionInfo()'         # evaluate an expression
rig run -r 4.5.3 -f analysis.R     # ... with a specific R version
rig run --cmd check --no-manual .  # run `R CMD check`

8. Turn on shell completions

rig ships PowerShell completions. See Installing auto-complete for how to load them from your profile.

Linux

1. Install the latest release

rig add release

Admin mode installs into /opt/R, so rig needs root, and re-runs itself under sudo:

Running `sudo` for adding new R versions. This might need your password.

rig installs a build made for your distribution. If there is none for your platform it falls back to a portable build and says so:

No distro-specific R build for platform `...`, falling back to the portable
build `...`.

See the supported distributions for the list.

Besides unpacking R, rig add also configures the CRAN and P3M repositories (P3M serves pre-compiled Linux binaries, which makes installing packages much faster), installs pak, sets R up to use a user package library, creates the quick links, and (if this is your first R version) makes it the default.

2. See what you have

rig list

* name   version  aliases
-------------------------
* 4.6.1           release

The * marks the default version. rig list --plain prints just the names, one per line, which is handy in shell scripts.

3. Add a second version

R versions are named with a version spec, not just a number:

rig add oldrel     # the previous minor release
rig add 4.4.3      # an exact version
rig add 4.4        # the latest patch release of 4.4.x
rig add oldrel/2   # two minor releases back
rig add devel      # the current R-devel
rig add next       # the current R patched / release candidate

rig available lists everything you can install, and rig available --list-distros the Linux distributions rig supports.

4. Switch the default version

rig default          # print the current default
rig default 4.5.3    # set it

The default version is the one the plain R and Rscript commands start. rig also creates versioned quick links, so you can always reach a specific version without switching:

R                              # the default version
R-4.5.3                        # a specific version
Rscript -e 'R.version.string'  # the default version, non-interactively

5. Install a package

rig add installed pak, so you can install packages straight away:

R -q -e 'pak::pkg_install("dplyr")'

Packages go into a per-user, per-version library that rig configured R to create automatically, so you do not need sudo to install packages even in admin mode, and packages for different R versions never collide.

Many R packages need system libraries to build. pak installs those automatically on supported distributions, asking for your password when it has to use the system package manager. Pass rig add --without-sysreqs if you would rather manage system dependencies yourself.

If you want more than one library for the same R version (say one per project), see the rig library command.

6. Run R without switching the default

rig run runs R, a script or a whole project with any installed version, leaving your default alone:

rig run                          # start R
rig run -f analysis.R            # run a script
rig run -e 'sessionInfo()'       # evaluate an expression
rig run -r 4.5.3 -f analysis.R   # ... with a specific R version
rig run --cmd check --no-manual .  # run `R CMD check`

7. Turn on shell completions

rig ships completions for bash, zsh, fish and elvish. See Installing auto-complete for the setup, which depends on how you installed rig.

Where to next

• Migrating to user mode: move this setup into your home directory later, with one command.
• Admin mode vs user mode: the concepts behind the two modes, and how to put rig’s directories somewhere else.
• CLI reference: every command and flag.
• rig repos: change which package repositories your R versions use.
• Docker containers: ready-made rig images for CI and reproducible builds.
• FAQ: the questions people ask most often.