rig system

Various commands to modify and configure the installed R versions. See their help pages for details. E.g. run rig system make-links --help.

Subcommands

add-pak
Install or update pak for an R version
allow-core-dumps macOS only
Allow creating core dumps when R crashes
allow-debugger macOS only
Allow debugging R with lldb and gdb
allow-debugger-rstudio macOS only
Allow debugging RStudio with lldb and gdb
blas macOS only
Manage the BLAS/LAPACK library used by R
clean-registry Windows only
Clean stale R related entries in the registry
detect-platform
Detect operating system version and distribution.
dirs
Print the directories rig uses
fix-aliases
Fix symbolic R-* quick links
fix-permissions macOS only
Restrict system library permissions to admin
fix-r-alias Windows only
Make the ‘R’ command start R in PowerShell
forget macOS only
Make system forget about R installations
make-links
Create R-* quick links
make-orthogonal macOS only
Make installed versions orthogonal
no-openmp macOS only
Remove OpenMP (-fopenmp) option for Apple compilers
script-assoc Windows only
Run .R files with rig from the Windows command line
setup-user-lib
Set up automatic user package libraries (alias: create-lib)
update-certs Linux only
Download the CA certificate bundle and configure R to use it
update-rtools40 Windows only
Update Rtools40 MSYS2 packages
user-mode
Switch to user mode and clean up admin-mode installations

rig system add-pak

Install/update pak for one or more R versions.

  • If --all is specified, then it installs pak for all current R installations.
  • If one or more R versions are specified, then it installs pak for those.
  • If no R versions are specified, then it installs pak for the default R installation, if there is one (see rig default).

Usage

rig system add-pak [OPTIONS] [version]...

Arguments

[version]...
R versions to install/update pak for

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
--all
Install pak for all R versions
--devel
Install the development version of pak (deprecated)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--pak-version <pak-version>
pak version to install. [default: stable]
[possible values: stable, devel]
--user
Run in user mode (overrides RIG_MODE and config)

rig system allow-core-dumps macOS only

Update the entitlements of the R process to allow core dumps on macOS. This command is similar to rig system allow-debugger but it also makes sure that the /cores directory of core dumps is writeable by the current user. Don’t forget to call ulimit -c unlimited from the same shell before starting R.

This command does nothing on Windows and Linux and in user mode.

In admin mode this command probably needs sudo: sudo rig system allow-core-dumps, otherwise rig will ask for your password.

Usage

rig system allow-core-dumps [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default is the default R version)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
--all
Update all R versions
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system allow-debugger macOS only

Update the entitlements of the R binary to allow debuggers on macOS. It adds the get-task-allow entitlement to the R binary. This is only needed for R installers 3.6 and later, previous versions are not signed. Call R -d lldb to start lldb on R. (Or R-x.y -d lldb if you want a non-default version.)

See also rig system allow-debugger-rstudio, which does the same for R running in RStudio.

This command does nothing on Windows and Linux and in user mode.

In admin mode this command probably needs sudo: sudo rig system allow-debugger, otherwise rig will ask for your password.

Usage

rig system allow-debugger [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default is the default R version)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
--all
Update all R versions
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system allow-debugger-rstudio macOS only

Update the entitlements of RStudio R process to allow debuggers on macOS. It adds the get-task-allow entitlement to the rsession (and rsession-arm64 on arm64 hardware) binary.

See also rig system allow-debugger, which does the same for R running outside of RStudio.

This command does nothing on Windows and Linux.

This command probably needs sudo: sudo rig system allow-debugger-rstudio, otherwise rig will ask for your password.

Usage

rig system allow-debugger-rstudio [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system blas macOS only

Commands to check or switch which BLAS/LAPACK library an installed R version uses. See rig system blas status --help and rig system blas set --help for details.

This is only supported on macOS. See the R for macOS FAQ for background on the reference BLAS vs. Apple’s Accelerate/vecLib BLAS.

This command does nothing on Windows and Linux.

Subcommands

set
Switch the BLAS/LAPACK library R uses
status
Show which BLAS/LAPACK library R is using

rig system blas set

Switch one or more installed R versions (default: all) to use either the reference BLAS that R ships by default, or accelerate, Apple’s Accelerate/vecLib BLAS, which is usually much faster for linear algebra.

rig system blas set accelerate
rig system blas set reference 4.4.1

This command only works on macOS. It skips (with a warning) any R version that does not ship the requested library.

In admin mode this command probably needs sudo: sudo rig system blas set accelerate, otherwise rig will ask for your password.

Usage

rig system blas set [OPTIONS] <blas> [version]...

Arguments

<blas>
BLAS library to use [possible values: reference, accelerate]
[version]...
R versions to update (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system blas status

For each installed R version (or the ones given), report whether it is using the reference BLAS that R ships by default, Apple’s accelerate (vecLib) BLAS, or an unknown library it cannot recognize.

This command only works on macOS.

Usage

rig system blas status [OPTIONS] [version]...

Arguments

[version]...
R versions to check (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system clean-registry Windows only

Remove R and Rtools entries from the Windows registry, if the corresponding R or Rtools versions are not installed any more.

This command does nothing on macOS and Linux.

Usage

rig system clean-registry [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system detect-platform

Detect and print the operating system version and distribution.

rig uses this information to choose the right R builds and package repositories. Use --json for machine-readable output.

The first line is the platform string of this machine. rig writes platform strings as target triples, with aarch64 or x86_64 as the arch:

  • aarch64-apple-darwin, x86_64-apple-darwin – macOS.
  • x86_64-w64-mingw32, aarch64-w64-mingw32 – Windows.
  • x86_64-unknown-linux-gnu – any Linux with glibc.
  • x86_64-unknown-linux-gnu-ubuntu-24.04 – a specific Linux distribution and version.

This is the form rproj.lock uses, and that rig prints in messages. Commands that take a platform, e.g. rig proj lock --platform or the RIG_PLATFORM environment variable, also take shorter forms: macos, windows, linux, macos-arm64, ubuntu-24.04, linux-ubuntu-24.04, and P3M platform names like jammy-x86_64. arm64 and amd64 work as arch names, too.

Set RIG_PLATFORM to make rig act as if it ran on another platform, e.g.:

RIG_PLATFORM=ubuntu-22.04 rig system detect-platform

Usage

rig system detect-platform [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--json
JSON output
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system dirs

Print the directories rig uses: where R and (on Windows) Rtools is installed, where the quick links are created, where (on Linux) rig keeps the fontconfig configuration and the fallback fonts of the portable R builds, where rig downloads the installers to, where rig keeps its own configuration, data, cache and log files, and the root rig proj centralizes project package libraries under, if configured.

The directories themselves may not exist.

Use --json for machine-readable output.

The output contains the directories in effect. They may be the defaults, or configured via the rig config file or environment variables.

Some directories may depend on the mode and on the architecture, e.g. on aarch64 Windows the R installation directory is different for aarch64 and x86_64 R builds.

Use --user and --admin to override the mode for a single invocation.

Printing a single directory

With one of the flags (see below) rig prints that single directory as a bare path, and nothing else, for use in a shell script:

cd "$(rig system dirs --r)"

The flags are mutually exclusive, and cannot be combined with --json.

--r is the directory that contains the directories of the individual R versions; it is not an R installation itself. Similarly --rtools is the directory that contains the Rtools directories. Use rig list --json and rig rtools list for the paths of the installed versions.

The Rtools installation root is only reported on Windows. On non-Windows platforms --rtools prints nothing and is hidden.

The fontconfig directory is only reported on Linux, where it holds the fonts.conf and the fallback fonts that rig installs for the portable R builds. On non-Linux platforms --fonts prints nothing and is hidden.

--download is the directory rig downloads the installers into. It is in the system temporary directory and its name contains your user id, so that admin and user mode installs, and different users of the same machine, never share it. See the download-dir configuration entry to change it.

--library-root is the root rig proj sync centralizes project package libraries under, if the RIG_PROJ_LIBRARY_ROOT environment variable or the proj-library-root configuration entry is set. Unset by default: each project’s library then stays at its own .rvenv/lib, and --library-root prints that fact instead of a path.

Usage

rig system dirs [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-a, --arch <arch> Windows only
Architecture of the R installation root (default: native arch). [possible values: x86_64, aarch64, arm64]
--binary
Print the quick link directory only.
--cache
Print rig’s cache directory only.
--data
Print rig’s data directory only.
--download
Print rig’s installer download directory only.
--fonts Linux only
Print the fontconfig directory only.
-h, --help
Print help (see a summary with ‘-h’)
--json
JSON output
--library-root
Print the centralized rig proj library root only.
--log
Print rig’s log directory only.
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--r
Print the R installation root only.
--rtools Windows only
Print the Rtools installation root only.
--user
Run in user mode (overrides RIG_MODE and config)

rig system fix-aliases

Check the symbolic quick links R-release, R-oldrel, R-devel and R-next (plus the -x86_64 variants on Arm machines) and make sure that each one points to the R version it currently should, i.e. the same version rig resolve would return for its name today.

In user mode R-devel/R-next install under a fixed directory name, so they are always already correct there. In admin mode the installation directory is named after the version number, so R-devel/R-next can go stale when devel/next branches to a new minor version; rig detects this the same way it names the directory in the first place.

If an alias points to the wrong version, rig re-points it to the correct one. If the correct version is not installed, rig removes the stale alias and prints a warning; it does not install R versions.

In user mode no administrator rights are needed. In admin mode you need an administrator account to run this command or use sudo on Unix, otherwise rig will ask for your password.

Usage

rig system fix-aliases [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system fix-permissions macOS only

Update the permissions of the current R versions on macOS, so only the administrator can install R packages into the system library. Together with rig system setup-user-lib this facilitates keeping additional packages in a user library, instead of the system library.

This command does nothing on Windows and Linux and in user mode.

rig add runs rig system fix-permissions, so if you only use rig to install R, then you do not need to run it manually.

In admin mode this command probably needs sudo: sudo rig system fix-permissions, otherwise rig will ask for your password.

Usage

rig system fix-permissions [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system fix-r-alias Windows only

Make the ‘R’ command start R in PowerShell.

PowerShell ships a built-in ‘r’ alias for ‘Invoke-History’, and because aliases take precedence over external commands, typing ‘R’ reruns the previous command instead of starting R. This command removes that alias in your PowerShell profile so that ‘R’ starts R via rig’s quick link.

It edits the ‘CurrentUserAllHosts’ profile of every PowerShell it finds (both ‘pwsh’ and ‘powershell’), in an idempotent, clearly marked block. Start a new PowerShell session for the change to take effect.

Use the ‘–undo’ flag to remove the block rig added, leaving the rest of the PowerShell profile(s) untouched.

This command does nothing on macOS and Linux.

Usage

rig system fix-r-alias [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--undo
Remove the block rig added to the PowerShell profile(s).
--user
Run in user mode (overrides RIG_MODE and config)

rig system forget macOS only

Tell macOS to forget about the currently installed R versions. This is needed to have multiple R installations at the same time.

This command does nothing on Windows and Linux and in user mode.

rig add runs rig system forget before and after the installation, so if you only use rig to install R, then you don’t need to run this command manually.

In admin mode this command probably needs sudo: sudo rig system forget, otherwise rig will ask for your password.

Usage

rig system forget [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system make-orthogonal macOS only

Make the current R installations orthogonal on macOS. This allows running multiple R versions at the same time.

This command does nothing on Windows and Linux, where R installations are automatically orthogonal. It also does nothing in user mode, as user mode installations are always orthogonal.

rig add runs rig system make-orthogonal automatically, you do not need to run it manually.

In admin mode this command probably needs sudo: sudo rig system make-orthogonal, otherwise rig will ask for your password.

Usage

rig system make-orthogonal [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system no-openmp macOS only

Remove -fopenmp flags from the R configuration, to make R work with the Apple compilers, instead of CRAN’s custom compilers. This is only needed for R 3.6.x and before.

rig add runs rig system no-openmp after the installation, so if only use rig to install R, then you don’t need to run this command manually.

This command does nothing on Windows and Linux and in user mode.

In admin mode this command probably needs sudo: sudo rig system no-openmp, otherwise rig will ask for your password.

Usage

rig system no-openmp [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system script-assoc Windows only

Run .R files with rig from the Windows command line, e.g. hello.R a b instead of rig run hello.R a b, in cmd and PowerShell.

This command associates .R files with rig, for the current user, and adds .R to the user’s PATHEXT, so Windows also finds hello.R on the PATH as hello. It runs rig run -f <file> for a .R file.

This also changes what happens when you double-click a .R file: it runs the script, instead of opening it in RStudio, Positron, RGui or another editor.

If you chose an app for .R files in the Open with dialog of Windows, then Windows uses that app, and rig cannot change it. rig warns about this. To use rig, choose R script (runs with rig) in Open with > Choose another app, with Always.

Open a new terminal for the PATHEXT change to take effect.

Use the --undo flag to remove the association, restore the previous default app of .R files, and remove .R from PATHEXT.

This command does nothing on macOS and Linux.

Usage

rig system script-assoc [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--undo
Remove the association, and restore the previous one.
--user
Run in user mode (overrides RIG_MODE and config)

rig system setup-user-lib

Alias: rig system create-lib

Set up R to create user package libraries when started, by default for installed R versions.

rig add runs rig system setup-user-lib, so if you only use rig to install R, then you do not need to run it manually.

Usage

rig system setup-user-lib [OPTIONS] [version]...

Arguments

[version]...
R versions (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system update-certs Linux only

Download the CA certificate bundle and configure R to use it (Linux only).

This helps R make HTTPS connections on systems where the default certificate store is missing or out of date.

Usage

rig system update-certs [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system update-rtools40 Windows only

Update Rtools40 compilers and libraries to the latest builds by updating the MSYS2 packages in Rtools40 on Windows.

This command does nothing on macOS and Linux.

In admin mode this command needs an administrator account.

Usage

rig system update-rtools40 [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig system user-mode

Switch rig to user mode and clean up the machine after admin mode.

In user mode rig installs R into your home directory (~/.local/share/rig/r or %APPDATA%\rig\data\r on Windows), and quick links into ~/.local/bin, so that rig never needs sudo. This command migrates an existing admin-mode setup to user mode:

  1. Sets the rig mode configuration to user.
  2. Reinstalls the admin-mode R versions in user mode, and restores the previous default version and version aliases. R versions that are already installed in user mode are not reinstalled. Use --no-reinstall to skip this step entirely and only clean up.
  3. Removes the system-wide admin-mode R installations.
  4. Removes the system-wide R-* quick links and the R/Rscript links.

Steps 3 and 4 remove files outside your home directory, so this command needs an administrator account or sudo on Unix, otherwise it will ask for your password.

Note that admin mode is rig’s default and the better tested mode, so there is no need to switch a working admin-mode setup. On Linux in particular, user mode uses portable (manylinux or musl) R builds and manylinux R packages, which are newer and less tested than the distro-specific builds and packages of admin mode. To go back to admin mode, run rig config set mode=admin and reinstall the R versions you want.

Use --keep-install to leave the admin-mode R installations in place (skipping step 3), and --keep-links to leave the system-wide links in place (skipping step 4). With both, nothing outside your home directory is touched and no administrator account or sudo is needed.

If you use Positron, it caches the list of R interpreters, so it may keep showing the old admin-mode installations and miss the new user-mode ones. Clear its interpreter cache, re-discover interpreters, and restart Positron to pick up the change.

Usage

rig system user-mode [OPTIONS]

Options

-h, --help
Print help (see a summary with ‘-h’)
--keep-install
Keep the admin-mode R installations, do not remove them.
--keep-links
Keep the admin-mode quick links, do not remove them.
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--no-reinstall
Do not reinstall admin-mode R versions in user mode.