r_version

The R version to install packages for, containing at least the major and minor versions.

Finding the Executable

The R version is found on the system according to the following guidelines:

Version Matching

rv utilizes a flexible version matching approach, similar to Posit Connect’s major-minor approach. If the patch version is specified, it will perform an exact match. If the patch version is not specified, it will match to any R version found with the same major and minor version.

For example, if R 4.5.0 and 4.5.1 are found on the system, the following matches will occur:

• r_version = "4.5" → 4.5.0 and 4.5.1
• r_version = "4.5.0" → 4.5.0

Since R packages are compatible across patch versions of R, it is recommended to specify only the major and minor version to increase cross-system compatibility.

Known Binary Locations

rv looks for an R matching the r_version of the project in the following order.

1. The R found on the PATH, if its version matches

2. The versioned links rig puts on the PATH rv v0.23.0, named after the version they point at: R-4.5, sometimes suffixed with -arm64/-x86_64, on macOS, R-4.5.1 on Linux and R-4.5.1.exe or R-4.5.1.bat on Windows.

3. The known installation locations of each OS:

   • Linux - the subdirectories of /opt/R (i.e. /opt/R/4.5.0/bin/R)
   • macOS - /Library/Frameworks/R.framework/Versions/* (the layout used by the CRAN installer) and /opt/homebrew/Cellar/r/* (Apple Silicon Homebrew installs). Intel Homebrew’s /usr/local/Cellar/r is not scanned.
   • Windows - the subdirectories of C:\Program Files\R and of %LOCALAPPDATA%\Programs\R

   Those installations do not need to be on the PATH: rv reads their version from the Rversion.h header they ship.

4. rig list --json rv v0.23.0, if rig is on the PATH but none of its installs were found by the steps above.

Note

• For interactive sessions of R in an rv project, if the R version does not match the R version in your config, rv enters a safe mode for that session: the library is redirected to a temporary directory (tempdir()/__rv_R_mismatch), so any package installs or loads during the mismatch silently use a throwaway library rather than the project’s real library. rv does not use the current R session, so packages may be installed for versions of R that your session is not currently using.

• When adding an R version to the path, the R executable is often within a bin/ directory

Overriding the R version

Introduced in rv v0.23.0

The commands that need to know which R to use take flags to override the discovery described above. Both have an environment variable equivalent, RV_R_BIN and RV_R_VERSION.

• --r-bin <PATH> - Use the R at that path instead of looking for one. Its version has to match the r_version of the project, otherwise rv errors and tells you what to pass to run with it anyway
• --r-version <VERSION> - The R version to use. On its own it can only ask for a version matching the project’s r_version, unless the command never runs R. Together with --r-bin, it asserts the version of that R and allows it to differ from the project

Running against an R that does not match the project is therefore a deliberate two step opt-in: --r-bin alone will not do it, since a wrong path should not quietly install packages for another R version.

What that means per command:

Commands	Overriding
rv plan, rv summary, rv tree, rv library	Those never run R, so --r-version alone is enough to see what the project would look like on another R version, even one that is not installed
rv sync, rv run	--r-bin together with --r-version runs against an R that differs from the project. The lockfile is then neither read nor updated, and rv warns about it
rv add, rv remove, rv upgrade	Only take --r-bin, and its version has to match the project. Those commands write the lockfile, so running them against another R is an error

use_devel

Introduced in rv v0.18.0

If you are running an R-devel build (identified by a non-empty status field in R’s Rversion.h), set use_devel = true alongside r_version so rv matches against that devel installation instead of a released version with the same major/minor version.

[project]
name = "devel project"
r_version = "4.6"
use_devel = true
repositories = [
    { alias = "PPM", url = "https://packagemanager.posit.co/cran/latest" },
]
dependencies = [
    "dplyr",
]

Default: false