Getting started in user mode
In user mode rig keeps everything inside your home directory, so it never needs sudo or an administrator account. Use this on a machine where you do not have administrator rights, or where you would rather not touch system directories.
If you do administer the machine and want a conventional system-wide R, follow Getting started in admin mode instead. For the trade-offs between the two modes, see Admin mode vs user mode.
User mode is newer than admin mode and has seen less use, so you are more likely to run into rough edges with it. This is most true on Linux, where user mode relies on portable (manylinux or musl) R builds and manylinux R packages. If you can use an administrator account and do not need R in your home directory, admin mode is the more conservative choice today. Please report any problem you hit.
0. Before you start
Install rig first. Check that rig works and see where it puts things:
rig --version
rig system dirsMode 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.
1. Switch rig to user mode
rig starts out in admin mode even when rig is installed into your home directory, so tell it to use user mode from now on:
rig system user-modeThis is the command the install script points you at when it finishes. On a machine with no system-wide R it has nothing to migrate or clean up, so it just records the setting and does not ask for your password.
Check where things will go from now on:
rig system dirsMode user
Architecture arm64
R root /Users/you/.local/share/rig/r
Binary dir /Users/you/.local/bin
...2. Install the latest release
rig add releaseR is installed under your home directory. 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.
3. Make sure ~/.local/bin is on your PATH
rig needs ~/.local/bin on your PATH for the R and Rscript commands to be found. It sets this up for you: it writes a small ~/.local/bin/rigenv snippet and sources it from your shell startup files (.profile, .bash_profile, .bashrc, .zprofile, .zshrc, and ~/.config/fish/conf.d/rigenv.fish if you use fish).
That only affects new shells, so for the session you are in rig tells you how to catch up:
⚠ /Users/you/.local/bin is not on the PATH.
To add it to the current session, run:
. "$HOME/.local/bin/rigenv" # bash/zsh/sh
fish_add_path "$HOME/.local/bin" # fish
New shell sessions will pick it up automatically.Check that it worked:
which R
R -q -e 'R.home()'4. See what you have
rig list* name version aliases
-------------------------
* 4.6.1 releaseThe * marks the default version. rig list --plain prints just the names, one per line, which is handy in shell scripts.
5. 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 candidaterig available lists the R versions you can install, but it leaves out intermediate patch releases. Use rig available --all to include everything.
6. Switch the default version
rig default # print the current default
rig default 4.5.3 # set itThe 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-interactivelyThe quick links are in ~/.local/bin.
7. 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 packages for different R versions never collide.
If you want more than one library for the same R version, e.g. one per project, see the rig library command.
8. Run R without switching the default
Another way to run a specific version without changing the default is rig run. It 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, which makes it a good fallback if you would rather not set up your PATH at all.
9. Turn on shell completions
rig ships completions for bash, zsh, fish and elvish. In user mode they are installed under the install prefix, e.g. ~/.local/share; see Installing auto-complete for how to load them.
10. macOS extras
- The menu bar app is not part of the user-mode archive, since it installs into
/Applications. - To debug R with
lldborgdb, runrig system allow-debugger. The CRAN builds are hardened against debuggers by default. In user mode this needs no password. There is alsorig system allow-debugger-rstudiofor RStudio’srsession, andrig system allow-core-dumps.
1. Switch rig to user mode
rig starts out in admin mode even when rig itself lives in your user profile, so tell it to use user mode from now on:
rig system user-modeThis is the command the install script points you at when it finishes. On a machine with no system-wide R it has nothing to migrate or clean up, so it just records the setting and does not raise a UAC prompt.
Check where things will go from now on:
rig system dirsMode user
Architecture x86_64
R root C:\Users\you\AppData\Roaming\rig\data\r
Binary dir C:\Users\you\.local\bin
...2. Install the latest release
rig add releaseNo UAC prompt this time: everything is written under your user profile.
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 the newly installed version 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.
3. Restart your terminal
rig adds the quick-link directory to your user PATH in the registry, and tells you that this needs a fresh terminal:
▶ Added C:\Users\you\.local\bin to user PATH
⚠ Restart your terminal (or sign out and back in) for the PATH change to take effect.Open a new terminal, then check that it worked:
Get-Command R
R -q -e 'R.home()'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.
4. See what you have
rig list* name version aliases
-------------------------
* 4.6.1 releaseThe * marks the default version. rig list --plain prints just the names, one per line, which is handy in scripts.
5. 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 candidaterig available lists the R versions you can install, but it leaves out intermediate patch releases. Use rig available --all to include everything.
6. Switch the default version
rig default # print the current default
rig default 4.5.3 # set itThe 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-interactivelyThe quick links are in your user profile, so switching the default never raises a UAC prompt.
7. 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 packages for different R versions never collide.
If you want more than one library for the same R version, e.g. one per project, see the rig library command.
8. Install Rtools
To build packages from source you need Rtools, which rig manages too, and in user mode installs into %APPDATA%\rig\data\rtools:
rig rtools list # what is installed
rig add rtools # every Rtools version your R versions need
rig add rtools45 # a specific Rtools versionrig 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.
9. Run R without switching the default
Another way to run a specific version without changing the default is rig run. It 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, which is handy before you have restarted your terminal.
10. Turn on shell completions
rig ships PowerShell completions. Dot-source the script from your PowerShell profile; for a user-mode install that is:
. "$env:USERPROFILE\.local\share\rig\_rig.ps1"See Installing auto-complete for the details.
1. Switch rig to user mode
rig starts out in admin mode even when rig itself lives in your home directory, so tell it to use user mode from now on:
rig system user-modeThis is the command the install script points you at when it finishes. On a machine with no system-wide R it has nothing to migrate or clean up, so it just records the setting and does not ask for your password.
Check where things will go from now on:
rig system dirsMode user
Architecture x86_64
R root /home/you/.local/share/rig/r
Binary dir /home/you/.local/bin
...2. Install the latest release
rig add releaseNo password prompt this time: everything is written under your home directory.
In user mode rig always installs a portable R build, one that does not depend on your distribution’s packages, picked for your libc (glibc or musl). Very old glibc versions are not supported; if yours is too old, rig says so instead of installing a broken R. rig also downloads a CA certificate bundle and points R at it, so HTTPS works even where the system store is missing or stale; you can re-run that step with rig system update-certs.
These portable builds are newer than the distro-specific builds that admin mode installs, and they are not as thoroughly tested yet, so you may hit the occasional rough edge with them. If that is a problem for you and you do have an administrator account, consider admin mode instead. Either way, please report what you run into.
Besides unpacking R, rig add also configures the CRAN and P3M repositories (P3M serves pre-compiled, self-contained Linux binaries, which makes installing packages faster and more robust), installs pak, 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.
3. Make sure ~/.local/bin is on your PATH
rig needs ~/.local/bin on your PATH for the R and Rscript commands to be found. It sets this up for you: it writes a small ~/.local/bin/rigenv snippet and sources it from your shell startup files (.profile, .bash_profile, .bashrc, .zprofile, .zshrc, and ~/.config/fish/conf.d/rigenv.fish if you use fish).
That only affects new shells, so for the session you are in rig tells you how to catch up:
⚠ /home/you/.local/bin is not on the PATH.
To add it to the current session, run:
. "$HOME/.local/bin/rigenv" # bash/zsh/sh
fish_add_path "$HOME/.local/bin" # fish
New shell sessions will pick it up automatically.Check that it worked:
which R
R -q -e 'R.home()'4. See what you have
rig list* name version aliases
-------------------------
* 4.6.1 releaseThe * marks the default version. rig list --plain prints just the names, one per line, which is handy in shell scripts.
5. 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 candidaterig available lists the R versions you can install, but it leaves out intermediate patch releases. Use rig available --all to include everything.
6. Switch the default version
rig default # print the current default
rig default 4.5.3 # set itThe 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-interactivelyThe quick links are in ~/.local/bin, so switching the default never needs a password.
7. 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 packages for different R versions never collide.
Many R packages need system libraries to build and run. pak can install those with your distribution’s package manager, but that needs sudo, which is exactly what user mode avoids. rig sets up P3M’s manylinux package repository binaries on glibc based Linux systems to fix this. These binary packages are self-contained and do not need any system libraries to run. The manylinux repository is fairly new, though, and not as thoroughly tested as P3M’s distro-specific repositories, so occasional problems with individual packages are still to be expected.
If P3M is missing a binary for a certain package, then you need to install this package form source. If the package needs system libraries, then you’ll need to install them yourself, or ask an administrator to install them.
P3M does not have binary packages for musl libc based Linux distributions (e.g. Alpine Linux).
If you want more than one library for the same R version, e.g. one per project, see the rig library command.
8. Run R without switching the default
Another way to run a specific version without changing the default is rig run. It 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, which makes it a good fallback if you would rather not set up your PATH at all.
9. Turn on shell completions
rig ships completions for bash, zsh, fish and elvish. In user mode they are installed under the install prefix, e.g. ~/.local/share; see Installing auto-complete for how to load them.
Where to next
- 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.