Admin mode vs user mode

rig can manage R installations in one of two modes. The current default is admin mode: R is installed system-wide, shared by every user on the machine, and most operations need sudo or an administrator account. In user mode rig installs everything into your home directory and never needs elevated privileges.

Admin mode is the older and better tested of the two, and it is what most rig users run today. User mode is newer, and on Linux it relies on portable (manylinux/musllinux) R builds and manylinux R packages that are still maturing. Pick admin mode if you can use an administrator account and want the best-trodden path; pick user mode if you cannot, or do not want to, touch system directories.

At a glance

Pros and cons

User mode Admin mode
Best for machines without admin rights shared servers, native Linux packages2
Maturity newer, less tested, esp. on Linux1 oldest and best tested, current default
Required privileges none sudo / administrator for many operations
Shared between users no yes
R install root in your home directory (see below) platform default (see below)
Needs PATH setup possibly3 usually no
Supported Linux distros all glibc and musl distros4 selected2
Multiple patch versions on macOS yes no5

  1. User mode is a recent addition to rig, so it has seen much less use than admin mode. This is most noticeable on Linux, where user mode always installs a portable R build and uses manylinux R packages; both are newer and less widely exercised than the distro-specific builds and packages that admin mode uses. Please report any problem you run into.

  2. In admin mode, on supported Linux distributions, rig installs R through the system package manager, so it is managed like any other distro package. R’s and R packages’ system libraries are shared with other users and also managed by the system package manager. System libraries for R packages can be automatically installed by pak.

  3. In user mode, the rig binary directory must be on your PATH for the R and Rscript commands to be found. rig helps with this and patches your shell profiles if the R binary directory is not already on your PATH.

  4. In user mode, on Linux, rig supports all glibc (>= 2.28) and musl (>= 1.2) distros. It uses self-contained R builds that do not depend on the system package manager or system packages. It sets up Posit Package Manager’s manylinux R package repositories to install self-contained binary R packages.

  5. In admin mode on macOS, rig can only install one patch version of any given minor version of R. For example, if you install R 4.5.1, rig will remove any other 4.5.x version that is already installed.

Where things go

Platform Mode R install root Binary directory (R, Rscript, R-*)
macOS admin /Library/Frameworks/R.framework /usr/local/bin
macOS user ~/.local/share/rig/r ~/.local/bin
Linux admin /opt/R /usr/local/bin
Linux user ~/.local/share/rig/r ~/.local/bin
Windows admin C:\Program Files\R C:\Program Files\R\bin
Windows user %APPDATA%\rig\data\r %USERPROFILE%\.local\bin

rig system dirs prints the directories rig actually uses on your machine, in the current mode and after applying any configuration overrides. It works without an R installation and is a good way to see where rig add will put things.

Admin mode

Admin mode is the current default, for historical reasons. Previous versions of rig only supported admin mode. R is installed into the platform’s usual system location and rig creates startup links (R, Rscript), and versioned R-4.5.1-style quick links in a system-wide binary directory that is normally already on everyone’s PATH.

Because these locations are outside your home directory, operations that write to them, e.g. adding or removing an R version, switching the default, creating the startup and quick links, switch to the root or administrator user as needed. On Unix rig runs sudo (prompting for your password); on Windows it elevates through a UAC prompt. On macOS admin mode also restricts the permissions of the system R library so that packages are not installed into it accidentally.

Admin mode may be the right choice on a server where you have administrator rights and want a single shared R for everyone. It may also be the right choice on Linux if you want rig to install R and R’s and R packages’ system dependencies through the system package manager so that it is managed like any other distro package.

It is also the mode with the most mileage on it: rig only supported admin mode for years, so if you have an administrator account and no reason to prefer user mode, this is the safer default today, on Linux in particular.

User mode

In user mode rig installs R entirely inside your home directory and creates the startup and quick links in a per-user binary directory. Nothing lives outside your account, so rig never needs sudo or an administrator account in this mode. It is designed for machines where you do not have, or do not want to use, elevated privileges.

The one thing to take care of is your PATH: the rig binary directory (~/.local/bin, or %USERPROFILE%\.local\bin on Windows) must be on it for the R and Rscript commands to be found. The user-mode install script sets this up for you; if you install rig from an archive manually. rig also checks if your PATH is set up correctly, and if not, it patches your shell profiles on Unix and updates your user environment variables on Windows.

WarningUser mode is newer

User mode is a much more recent feature than admin mode, so it is less tested. On Linux especially: user mode always installs a portable (manylinux or musl) R build and uses manylinux R packages from P3M, and those are not as battle-hardened as the distro-specific builds and packages of admin mode. If you have an administrator account and no particular reason to keep R inside your home directory, admin mode is the more conservative choice for now. Either way, please report problems you hit.

Whichever mode you decide on, you can pin it explicitly with the steps below, instead of relying on rig’s default.

How rig picks the mode

rig resolves the mode from the first of these that is set, and otherwise defaults to admin mode:

  1. The global --user / --admin flags on the command line.
  2. The RIG_MODE environment variable (user or admin).
  3. The mode key in the rig config file.

So you can choose the mode at three different scopes:

# Just this one command:
rig add release --user

# For a shell session (or exported in your profile):
export RIG_MODE=user

# Persistently, saved in the rig config file:
rig config set mode=user
rig config set mode=admin

Switching an existing setup to user mode

If you already have an admin-mode setup, rig system user-mode migrates it in one step:

  1. It sets the rig mode configuration to user.
  2. Reinstalls your admin-mode R versions in user mode and restores the previous default version and version aliases. (R versions already present in user mode are not reinstalled.)
  3. Removes the system-wide admin-mode R installations.
  4. Removes the system-wide startup and quick links.

Steps 3 and 4 delete files outside your home directory, so they need sudo or an administrator account, rig asks for your password for just that part. Use --no-reinstall to skip the reinstall and only clean up, or --keep-install and --keep-links to leave the admin-mode installations and/or links in place. With both --keep-* flags nothing outside your home directory is touched, so no elevated privileges are needed at all.

To go back, set the mode to admin again (rig config set mode=admin) and reinstall the R versions you want.

Mixing admin and user mode

You can mix admin and user mode on the same machine, but it is not recommended. The main reason is that it is easy to set up your PATH incorrectly and end up with the wrong R and Rscript commands being found. E.g. on macOS or Linux both /usr/local/bin/R and ~/.local/bin/R exist and the one that is found first on your PATH is used.

Advanced: custom directories

You can override where rig puts things with an environment variable or a config key:

  • Quick-link directory: RIG_BINARY_DIR env var, or the binary-dir config key. This applies in both modes, overriding the default /usr/local/bin (admin) or ~/.local/bin (user). If you change this, rig never modifies your shell config files or your PATH in the Windows registry.
  • R install root: RIG_R_INSTALL_DIR env var, or the r-install-dir config key. This only takes effect in user mode. In admin mode R is installed by the platform installer (the Apple .pkg, the Windows installer, or a Linux distribution package) to its fixed system location and cannot be relocated.

See also