Skip to contents

Access the paths that renv uses for global state storage.

Usage

paths

Format

An object of class list of length 5.

Details

By default, renv collects state into these folders:

PlatformLocation
Linux~/.local/share/renv
macOS~/Library/Application Support/renv
Windows%LOCALAPPDATA%/renv

For new installations of renv using R (>= 4.0.0), renv will use tools::R_user_dir() to resolve the root directory. If an renv root directory has already been created in one of the old locations, that will still be used. This change was made to comply with the CRAN policy requirements of R packages. By default, these paths resolve as:

PlatformLocation
Linux~/.cache/R/renv
macOS~/Library/Caches/org.R-project.R/R/renv
Windows%LOCALAPPDATA%/R/cache/R/renv

If desired, this path can be customized by setting the RENV_PATHS_ROOT environment variable. This can be useful if you'd like, for example, multiple users to be able to share a single global cache.

The various state sub-directories can also be individually adjusted, if so desired (e.g. you'd prefer to keep the cache of package installations on a separate volume). The various environment variables that can be set are enumerated below:

Environment VariableDescription
RENV_PATHS_ROOTThe root path used for global state storage.
RENV_PATHS_LIBRARYThe path to the project library.
RENV_PATHS_LIBRARY_ROOTThe parent path for project libraries.
RENV_PATHS_LIBRARY_STAGINGThe parent path used for staged package installs.
RENV_PATHS_CELLARThe cellar, containing local package binaries and sources.
RENV_PATHS_SOURCEThe path containing downloaded package sources.
RENV_PATHS_BINARYThe path containing downloaded package binaries.
RENV_PATHS_CACHEThe path containing cached package installations.
RENV_PATHS_PREFIXAn optional prefix to prepend to the constructed library / cache paths.
RENV_PATHS_RTOOLS(Windows only) The path to Rtools.
RENV_PATHS_EXTSOFT(Windows only) The path containing external software needed for compilation of Windows source packages.
RENV_PATHS_MRANThe path containing MRAN-related metadata. See vignette("mran", package = "renv") for more details.

Note that renv will append platform-specific and version-specific entries to the set paths as appropriate. For example, if you have set:

Sys.setenv(RENV_PATHS_CACHE = "/mnt/shared/renv/cache")

then the directory used for the cache will still depend on the renv cache version (e.g. v2), the R version (e.g. 3.5) and the platform (e.g. x86_64-pc-linux-gnu). For example:

/mnt/shared/renv/cache/v2/R-3.5/x86_64-pc-linux-gnu

This ensures that you can set a single RENV_PATHS_CACHE environment variable globally without worry that it may cause collisions or errors if multiple versions of R needed to interact with the same cache.

If you need to share the same cache with multiple different Linux operating systems, you may want to set the RENV_PATHS_PREFIX environment variable to help disambiguate the paths used on Linux. For example, setting RENV_PATHS_PREFIX = "ubuntu-bionic" would instruct renv to construct a cache path like:

/mnt/shared/renv/cache/v2/ubuntu-bionic/R-3.5/x86_64-pc-linux-gnu

If this is required, it's strongly recommended that this environment variable is set in your R installation's Renviron.site file, typically located at file.path(R.home("etc"), "Renviron.site"), so that it can be active for any R sessions launched on that machine.

Starting from renv 0.13.0, you can also instruct renv to auto-generate an OS-specific component to include as part of library and cache paths, by setting the environment variable:

RENV_PATHS_PREFIX_AUTO = TRUE

The prefix will be constructed based on fields within the system's /etc/os-release file.

If reproducibility of a project is desired on a particular machine, it is highly recommended that the renv cache of installed packages + binary packages is backed up and persisted, so that packages can be easily restored in the future -- installation of packages from source can often be arduous.

If you want these settings to persist in your project, it is recommended that you add these to an appropriate R startup file. For example, these could be set in:

  • A project-local .Renviron;

  • The user-level .Renviron;

  • A file at file.path(R.home("etc"), "Renviron.site").

Please see ?Startup for more details.

Package Cellar

If your project depends on one or R packages that are not available in any remote location, you can still provide a locally-available tarball for renv to use during restore. By default, these packages should be made available in the folder as specified by the RENV_PATHS_CELLAR environment variable. The package sources should be placed in a file at one of these locations:

  • ${RENV_PATHS_CELLAR}/<package>_<version>.<ext>

  • ${RENV_PATHS_CELLAR}/<package>/<package>_<version>.<ext>

  • <project>/renv/cellar/<package>_<version>.<ext>

  • <project>/renv/cellar/<package>/<package>_<version>.<ext>

where .<ext> is .tar.gz for source packages, or .tgz for binaries on macOS and .zip for binaries on Windows. During restore(), renv will search the cellar for a compatible package, and prefer installation with that copy of the package if appropriate.

Projects

In order to determine whether a package can safely be removed from the cache, renv needs to know which projects are using packages from the cache. Since packages may be symlinked from the cache, and symlinks are by nature a one-way link, projects need to also report that they're using the renv cache.

To accomplish this, whenever renv is used with a project, it will record itself as being used within a file located at:

  • ${RENV_PATHS_ROOT}/projects

This file is list of projects currently using the renv cache. With this, renv can crawl projects registered with renv and use that to determine if any packages within the cache are no longer in use, and can be removed.

Examples

# get the path to the project library
path <- renv::paths$library()