Reproducible Environments with renv

R’s own vocabulary is the first thing to get straight. The R FAQ answers "What is the difference between package and library?" with a definition that renv’s documentation repeats: a library is a directory that contains installed packages, and a package is what library(dplyr) loads from one. A repository is a source of packages, such as CRAN, Bioconductor, Posit Public Package Manager or an r-universe, that install.packages() downloads from into a library. .libPaths() lists the libraries R searches, in order, and getOption("repos") lists the repositories it installs from. Both are covered, with install.packages() and update.packages(), on Packages, Libraries and Namespaces. renv changes the first list: a project that uses renv has its own library first on .libPaths(), and nothing from the user or site libraries after it except the packages that ship with R.

The renv introduction names the three gains this buys. Isolation: installing, updating or removing a package in one project cannot affect another. Portability: the lockfile records enough metadata about every package for it to be installed again on another computer. Reproducibility: the lockfile records the versions, so the same versions come back. The cost is also stated in the documentation: an isolated project never benefits from bug fixes in its packages unless somebody updates it, so the advice is to run renv::update() regularly (at least once a year, says the introduction), re-run the code, and snapshot again.

renv is also explicit about what it does not do. It tracks the version of R in the lockfile but cannot change it, because it runs inside R. It does not restore pandoc, which rmarkdown needs and does not bundle. It does not control the operating system, the system libraries, the compilers or the BLAS and LAPACK libraries that compiled packages are built against, and package installation can fail if a package was originally installed from a binary that is no longer available, because renv then tries to build it from source and may lack the system prerequisites. The last sections of this page return to R itself, and to the system layer, with rig and Docker. The renv documentation also notes that the workflow is generally a poor fit for a CRAN package, because CRAN checks a package against the latest versions of its dependencies; the usual place for renv is an analysis, an application or a report, not a library.

The project below lives in ~/project. It is a script that uses jsonlite and R6, one with library() and one with ::. The first script writes report.R, shows it, and asks renv which packages it finds. renv::dependencies() returns a data frame that maps packages to the files in which they were found; its Source column holds absolute paths, so the script keeps only the file names.

Source: renv package documentation: dependencies

Before this point renv has not been used in the directory, and dependencies() works anyway: it only reads files. The Require and Version columns stay empty for packages found in code, and Dev is TRUE for development dependencies, which are described below.

Three of renv’s functions start from the same question: which packages does this project use? init() installs them, snapshot() (with the default snapshot type) records them, and status() compares them with the lockfile and the library. The answer comes from renv::dependencies(), which is static analysis: it parses the code and looks at what it says, and it does not run anything. The help page lists what it recognises: calls of the form library(package), require(package), requireNamespace("package") and package::method() (and :::), the box::use() and pacman::p_load() loaders, the rlang::check_installed() and rlang::is_installed() checks, and, in later releases, base::use() (renv 1.1.5), data(dataset, package = "package") (1.1.6) and system.file(..., package = "package") (1.2.0). It reads .R files, R Markdown and Quarto documents, DESCRIPTION files and Jupyter notebooks. R Markdown files need the rmarkdown package, and the YAML header needs yaml; in a project library that has neither, dependencies() warns that the yaml package is required to parse dependencies within R Markdown files, and suggests installing it.

The script builds a scratch tree with a script, a notebook-style document and a DESCRIPTION, and prints which package was found in which file. It runs before the project is initialised, because the project library below will not contain rmarkdown and yaml.

Source: renv package documentation: dependencies

Each step shows a rule of the scan. The first listing finds dplyr (a library() call), ggplot2 (a quoted library() argument), stringr (requireNamespace()), jsonlite (a :: call) and data.table (a ::: call) in analysis.R, rmarkdown and knitr in the document, and cli from the Imports field of the DESCRIPTION. It does not find DBI, whose library() call is in a chunk with eval=FALSE, because renv skips chunks that are not evaluated, nor shiny, in a chunk marked renv.ignore=TRUE; renv.ignore=FALSE forces a chunk to be read. It also does not find lubridate and forcats, because the loop for (p in c(...)) library(p, character.only = TRUE) hides the names from a parser. The documentation gives that very loop as an example of what static analysis cannot see, and gives the escape hatch used in the script: a file called _dependencies.R that holds plain library() calls. A package that only another package needs at run time cannot be seen either (tidyr::separate_wider_delim() needs stringr, which tidyr only suggests); for a few common cases renv infers the indirect dependency (dplyr with DBI and RSQLite implies dbplyr), and options(renv.dependencies.implied = list()) turns the inference off.

testthat appears in the second listing, with Dev set to TRUE: a package in the Suggests field of the project’s DESCRIPTION is a development dependency, one that people need while working on the project and the computer deploying it does not. snapshot() and status() leave development dependencies out of the lockfile by default (renv 1.0.0), while renv::install() with no arguments installs them. The snapshot.dev setting (renv 1.1.6) turns them on for snapshot() and status(). Packages used in the user’s ~/.Rprofile also count as development dependencies, when config$user.profile() is TRUE.

The last listing shows the other control on the scan. renv reads the project’s .gitignore files to decide which files to skip, and a .renvignore file with the same syntax takes its place in the folder that contains it; data/old-script.R disappears once data/ is ignored. Ignoring matters for speed (renv reports when a scan finds more than 1000 files, renv.config.dependencies.limit) and for errors: a file that does not parse is reported, not fatal, unless errors = "fatal" or the config option dependency.errors says so. Profile-specific sections in these files start with a comment of the form #| profile == "dev".

The renv FAQ turns this into the answer to the most common question: a package enters the lockfile only if it is both installed in the project library and used by the project according to dependencies(). To record every installed package whatever the code says, use the all snapshot type below; to list packages one by one, use explicit; to keep a package out, add it to the ignored.packages setting.

renv::init() turns a project into an renv project. Its help page lists four steps: set up the project infrastructure (the project library and the .Rprofile line that activates it), discover the packages the project uses with dependencies() and install them into the project library (the job of hydrate()), write a lockfile that records the library (the job of snapshot()), and restart R if it runs inside RStudio. If the project already uses renv, init() restores the library when it is missing and otherwise asks what to do. The main arguments are in the table.

Source: renv package documentation: init

There is one point about repositories that decides what the lockfile will say. If the repos option has not been set by some other means, init() uses the Posit Public Package Manager CRAN mirror, because it can serve pre-built binaries on common Linux distributions; the NEWS for renv 1.0.0 introduced this. The scripts here set the option to the public CRAN address first so that the lockfile records that address, which is also what a project does when its .Rprofile or Rprofile.site sets repos. The initial run:

Source: renv package documentation: init

The report reads from the top: renv linked the packages the project uses into the new project library (the packages came from the libraries that were already on the machine, which is what hydrate() does), then snapshot() listed what it would write into the lockfile and wrote it. The heading # RSPM --- above the three packages names the repository recorded in each package’s own DESCRIPTION (packages from different repositories would be listed under one heading each): the packages of the machine used here were built from Posit Public Package Manager binaries, whose Repository field says RSPM, whereas packages installed from CRAN say CRAN. The lockfile also records renv itself, so that a restore can bring back the same version of the tool, and the version of R, 4.6.1. renv::status() then confirms that the library, the lockfile and the code agree.

renv::init(bare = TRUE) is the variant for starting with an empty library, and it is the form the examples in the renv help pages use. A project that needs no packages yet, or one that wants to install everything itself, can use it, and a later renv::snapshot() records whatever has been installed and used.

The second script looks at the project from the inside. It is run in a new R session, as the next script of any workflow would be, and that matters: nobody calls renv::load() here. The session started in ~/project, R read the project’s .Rprofile, and that line activated the project.

Source: renv package documentation: Introduction to renv

The files are those the introduction lists, plus the directory renv keeps its machinery in:

Source: renv package documentation: Introduction to renv

Four details in the output are worth reading slowly. The project library is first on .libPaths(), and the only other entry is R’s own library of base and recommended packages: the user and site libraries are gone, which is why library(dplyr) fails in the script even though dplyr is installed on the machine. The error is the ordinary one for a missing package; a project that needs dplyr has to install it into its own library. jsonlite and R6 in the project library are symbolic links into the cache, which the later section on the cache explains, while renv itself is a real directory, not a link. And find("install.packages") reports renv:shims before package:utils: renv puts shims on the search path so that the habitual install.packages(), update.packages() and remove.packages() call renv::install(), renv::update() and renv::remove() instead, and the shim can be bypassed by writing utils::install.packages(). renv::load(), which the autoloader calls, is the function that sets all this up, including a sandbox of the system library that hides non-base packages (the sandbox is configurable, renv.config.sandbox.enabled).

renv.lock is JSON, so that other tools can read it. The lockfile article describes four kinds of record: the version of R, the repositories that were active when the lockfile was written, and one record per package with its version and installation source. The lockfile written here has the two keys R and Packages, and renv itself is one of the package records. The script prints the top of the file, reads it back with renv::lockfile_read(), which returns a list, and then writes the same snapshot in the older, compact format that renv produced before version 1.1.0, so that a record fits on a screen, and prints its first record. In that format each package carries a Hash, and the hash is the name of the directory the package has in the cache.

Source: renv package documentation: Anatomy of a lockfile

The table lists the fields of a record. In the format of renv 1.1.0 and later the record is a copy of the installed package’s DESCRIPTION fields, which is why the R6 record above has 19 fields, of which the script prints the first ten; the compact format keeps only the first group.

Source: renv package documentation: Anatomy of a lockfile

A lockfile can be edited by hand, and the renv FAQ says what that costs: a record without a Hash cannot use the global cache, so the package is always installed again. renv::lockfile_validate() checks a lockfile against renv’s JSON schema (it needs the jsonvalidate package, and since renv 1.3.1 it says so clearly when it is missing). The family lockfile_create(), lockfile_read(), lockfile_write() and lockfile_modify() reads and writes lockfiles from code, and renv::record() adds or removes a single package record. The format changed in renv 1.1.0: records now include more of the DESCRIPTION, which lets other tools recompute the hash from the lockfile alone, and options(renv.lockfile.version = 1), or the environment variable RENV_LOCKFILE_VERSION=1, asks for the compact one. renv 1.2.0 strips credentials embedded in repository URLs (https://user:token@host/path becomes https://host/path) when it writes the lockfile, which the lockfile.sanitize setting controls.

The working loop has four verbs, and the first two are the ones a person types most. The code starts to use a package, which is installed into the project library; once the code works, renv::snapshot() records the library in the lockfile; the lockfile goes into version control; and anybody else, or the same person on another computer, runs renv::restore() to get the library back. renv::status() reports whether the three things that should agree really do: the code (what dependencies() finds), the library and the lockfile.

The next script plays the first half. The project starts to use tinytest, a small testing package that is not installed. status() notices, renv::install() installs it (this needs the network, because tinytest is not in the cache yet; the script prints only the summary lines of renv’s progress report), and status() notices again that the library has a package that the lockfile does not know about.

Source: renv package documentation: status

The two reports are the two halves of one table in the status() help page. The help page says that the function checks installation first, because a missing package could be a dependency of a package that is used, and only then compares the lockfile with the code, and then versions.

Source: renv package documentation: status

When R starts in a project, renv runs the same check and prints a one-line notice. A new session started now, with tinytest installed and not recorded, begins with the first line below, and a session that starts in a fresh clone, where the project library does not exist yet, begins with the two lines of the second block. Both come from renv::load(), and the check can be switched off with the synchronized.check config option.

Source: renv package documentation: status

Source: renv package documentation: status

The second half of the loop, run in that new session, is snapshot() and restore(). The script also removes the package again to show a restore with something to do: the report names the package, its version and where it comes from, and, because tinytest is in the cache, the install is a link. A restore with nothing to do ends in one line.

Source: renv package documentation: snapshot

snapshot() prints what it would change in the lockfile, in the form [old -> new] where a star means "not recorded", writes the file, and when called interactively it asks first (prompt = interactive()); renv 1.0.0 stopped asking for confirmation when the lockfile does not exist yet, since deleting it undoes the write. It checks the library before writing (the snapshot.validate config option, on by default) and diagnoses problems such as an installed package whose dependency is missing. Its other arguments are worth knowing: lockfile writes elsewhere, and lockfile = NULL returns the lockfile as an R object without writing, which the snapshot-type section uses; packages and exclude restrict what is recorded (a package’s dependencies are always added, so the lockfile stays complete); update = TRUE keeps the records of packages that are not in the library any more; repos chooses the repositories recorded; type selects the snapshot type; and force writes even when the checks failed. Setting renv.config.auto.snapshot to TRUE makes renv snapshot after each change without being asked, and is off by default.

restore() compares the lockfile with the project library and installs, from the lockfile’s records, the packages that differ. Its arguments change how it does that.

Source: renv package documentation: restore

Since renv 1.2.0 install() and restore() download and install packages in parallel: downloads are batched into one curl --parallel call and source packages are built concurrently, up to install.jobs at a time (default 4), each as soon as its dependencies are ready. Binary packages are installed first because they need no build order.

Restoring a project that needs forty packages would be slow if every project had to download, and for packages with C or Fortran code compile, its own copies. The renv package avoids that with a cache that all of a user’s renv projects share. The package-installation article describes what happens when a package is requested, whether by install.packages() (through the shim), renv::install() or restore(). If the requested version is in the cache, it is linked into the project library, and that is all. Otherwise the package is downloaded and installed into the project library, then copied into the cache and linked back. A project library entry is therefore a link into the cache, and two projects that use the same version of a package share one copy on disk. The script looks at the cache and at one of those links; the last two lines call renv::isolate(), which undoes the sharing for this project.

Source: renv package documentation: Installing packages

Four things in the output are worth reading. The cache path ends with the platform components that renv appends to whatever location is configured: a cache version (v5 for renv 1.3.1), a prefix that names the operating system, the R minor version (R-4.6) and the platform. A cache built for R 4.5 is a different directory, and two different Linux distributions do not collide. Below that is one directory per package, then per version, then per hash; the hash is the Hash of the package’s compact lockfile record, and the output of the lockfile script showed it to be the directory name. The project’s R6 is a symbolic link to that directory. And renv itself is not in the cache.

Where renv keeps things is controlled by environment variables. By default the root is ~/.cache/R/renv on Linux, ~/Library/Caches/org.R-project.R/R/renv on macOS and %LOCALAPPDATA%/R/cache/R/renv on Windows, and the cache is a directory below it; earlier versions used other folders (~/.local/share/renv on Linux), which renv still uses if it already exists there. renv::paths is a list of functions that return each location, and the variables are:

Source: renv package documentation: paths

The paths reference adds two warnings. Set the variables in an R startup file so that they apply to every session: a project-local .Renviron, the user’s ~/.Renviron, or the site-wide Renviron.site, which is the right place for a cache shared by all users of an R installation (the startup order is on Sessions, Workspaces and Startup). And if reproducibility on a machine matters, back up and persist the cache: restoring from it is much easier than installing an old package from source again. A shared cache needs more care: the files in it must be readable by every user, access control lists included, and the RENV_CACHE_USER variable makes renv change the owner of cached packages. Two failure modes have their own tools. renv::purge("pkg") removes a corrupted package from the cache, and renv::restore(rebuild = TRUE), renv::install("pkg", rebuild = TRUE) or renv::rebuild() install again past it.

The cache can be turned off per project with renv::settings$use.cache(FALSE), or for a user with renv.config.cache.enabled. renv.config.cache.symlinks chooses between links and copies. It matters when the library and the cache are on different volumes, or when the project goes somewhere the links cannot follow, such as the image of a Docker build: renv.config.cache.symlinks = FALSE copies, so that nothing in the project library points outside it. renv::isolate(), which the script ran, copies the linked packages into the project library and leaves the cache in use for future installs. Finally, renv.config.install.shortcuts, on by default, lets renv install a local copy of a package it finds already installed in the user or site libraries, and renv::hydrate(), which init() calls, does the same job for a whole project: it copies the packages the project uses from the system libraries, then the cache, and installs from the repositories only what it does not find. That is why the init() run above needed no download.

The default implicit snapshot records the packages that dependencies() finds, as seen above. Two others exist for people who prefer a different contract, and a fourth lets code decide. renv::settings$snapshot.type() reads the project’s type, and renv::settings$snapshot.type("explicit") changes it (it is saved in renv/settings.json); the type argument of snapshot() changes it for one call. The script asks for what each type would record, without writing the lockfile, by passing lockfile = NULL, and installs magrittr first, a package that nothing in the project uses, to make all show its difference.

Source: renv package documentation: snapshot

Source: renv package documentation: snapshot

The help page also describes package projects, that is, projects with a DESCRIPTION at the top: renv records the package’s dependencies and not the package itself. Config/renv/snapshot/include-self: TRUE in the DESCRIPTION includes the package too (renv 1.2.4), for example for a Shiny application that is developed as a package and deployed by name. renv::init() prompts for a snapshot type when the project has a top-level DESCRIPTION (renv 1.0.0). The package structure is on Creating Packages.

After init() the usual commands keep working, because of the shims, and renv has its own. The introduction says that one of renv’s philosophies is that existing package-management habits should continue to work. renv::install() differs from install.packages() in that it uses the cache, knows several sources, and, when it is called with no arguments, installs every package the project requires, development dependencies included. It does not read the lockfile: it installs the latest versions available, unless a version is given. The package names can carry a source, in a subset of the syntax of the remotes package with one deviation, which is that a subdirectory is separated by a colon:

Source: renv package documentation: install

The other arguments are include and exclude (restrict the packages of a project-wide install), library, type ("source" or "binary", default getOption("pkgType")), rebuild, repos, dependencies (which DESCRIPTION fields count; the default is the package.dependency.fields setting), transactional, and lock = TRUE, which updates renv.lock after the packages have installed. Since renv 1.3.0 the version constraints in the project’s own DESCRIPTION (dplyr (>= 1.1.0) in Imports) are honoured by install() and validated by snapshot(); and since 1.3.1 install() signals an error when a requested package fails to install, even if an older copy remains. The tinytest and magrittr installs above, and the R6 install below, went through this function.

renv::update() brings installed packages up to date. It looks only at the source a package was installed from, so a package installed from GitHub is not updated from CRAN. With check = TRUE it reports what is available without installing anything, which is what the script below does; with lock = TRUE it updates the lockfile afterwards; since renv 1.1.3 it looks only at the project library unless all = TRUE. It updates renv itself too (renv::upgrade() updates only renv, or installs a development version from GitHub). The recommended routine, from the introduction, is to run update(), then the project’s code, and then snapshot(); if the update breaks something, restore() goes back to the lockfile. renv::remove("pkg") removes a package from the project library; it asks for confirmation only when the target is not the project library (renv 1.2.4).

A few more functions are used less often, and the table says what each is for.

Source: renv package documentation: reference index

renv can also use the pak package to install packages. It is off by default (renv.config.pak.enabled); when it is on and pak is itself in the lockfile, restore() installs and uses that recorded version of pak (renv 1.3.1).

A lockfile in version control is a history of the project’s dependencies. renv::history() uses git to list the commits that changed the lockfile, as a data frame with the columns commit, author_date, committer_date and subject; renv::revert(commit) checks the lockfile out of an older commit. Both are implemented for git only. revert() changes the lockfile and nothing else, and leaves it as an uncommitted modification, so it is followed by restore(), which makes the library match, and by a commit if the change is to be kept. The script sets up a repository with the commit dates fixed so that the output is the same on every run, puts an older R6 in the lockfile, and goes back. It installs R6 2.5.1 from the CRAN archive, which needs the network.

Source: renv package documentation: history

The output has the whole story. git ls-files shows what a project tracks: .Rprofile, renv.lock, renv/activate.R, renv/settings.json, renv/.gitignore and the code, and nothing of the library. status() reports the R6 mismatch in two parts at once: the version (2.6.1 against 2.5.1) and the repository (RSPM against CRAN), because 2.5.1 came from the CRAN archive and its DESCRIPTION says CRAN. update(check = TRUE) reports that 2.6.1 is available. After snapshot() the lockfile pins 2.5.1; history() lists the two commits; revert() restores the earlier lockfile; status() sees the library and the lockfile disagree again in the other direction; and restore() reinstalls 2.6.1 from the cache. The comment in the script explains one oddity: revert() ends by running git diff on the lockfile and the diff goes straight to the terminal, bypassing R’s output; the script points git at an external diff program that prints nothing, so that the diff does not interrupt the transcript. In an ordinary terminal that diff is part of what revert() shows.

The point of the lockfile is the other computer. The commands below clone the committed project, start R in the clone with an empty package cache, so that nothing is available locally, and restore. This stands for a colleague’s first day, or for a build server. It needs the network: renv bootstraps itself, and the packages are downloaded and built from source.

Source: renv package documentation: Introduction to renv

Source: renv package documentation: Introduction to renv

The first lines of the output are the listing of the clone (the .git directory, renv/, renv.lock, report.R and .Rprofile; the directory order depends on the locale). The first Rscript ran .Rprofile, which ran renv/activate.R; the autoloader did not find renv 1.3.1 and bootstrapped it, that is, downloaded and installed it. The renv documentation says that renv does not have to be installed beforehand. It then reported the state of the project: none of the recorded packages is installed. restore() printed the plan, grouped by the repository each record names, downloaded the three packages, and built them (the packages are downloaded in parallel, so the order of the lines in the download group can differ from run to run). The status() that follows finds no issues.

The renv introduction states what to commit: renv.lock, .Rprofile, renv/settings.json and renv/activate.R, together with renv/.gitignore, which renv creates so that a plain git add . takes the right files. A collaborator who opens the project then gets renv bootstrapped, and renv offers to run restore(). If the project is returned to after a long time, the FAQ separates two intents: a "time capsule" is a restore() of the lockfile, possibly with the old version of R installed again, and a project with fluid dependencies starts with update(), then the code, then snapshot().

Everything above relies on the project being active. A session that does not load the project is a common source of confusing results, and renv can only warn the people who are there to read the warning, the interactive users. The next script is run as Rscript --no-init-file, which skips the user profile, so the .Rprofile of the project is not read; R_PROFILE_USER set to another file, or a launcher that starts R in a different directory, would do the same. Nothing is activated, renv::project() is NULL, and renv sees whichever libraries the machine has. The script calls snapshot() with a different lockfile path, so that the project’s lockfile is not touched.

Source: R documentation: Startup

Source: renv package documentation: config

The lockfile that comes out has lost tinytest, because tinytest is installed in the project library and the session looks in the machine’s. Nothing stopped the snapshot: renv names the missing package and goes on, and with prompt = FALSE there is nobody to ask. Packages that do exist in the machine’s libraries would be recorded at the machine’s versions, not at the project’s. In an interactive session renv does ask: the activate.prompt config option (on by default) makes snapshot() and restore(), in a project that has not been activated, offer to activate it, to continue with the current library paths, or to cancel. The last lines of the script print its wording from renv’s source, with an internal function, to show it; the function name is not part of the interface.

A project is the right unit for an analysis with many files, and the wrong one for a script that is sent by itself. renv::use() is renv’s lightweight answer: it describes the packages in the script and their versions, builds a library for the script in R’s temporary directory, installs the requested packages and their recursive dependencies into it, and puts it on the library paths for the rest of the session. By default isolate = TRUE, so only the requested packages are visible besides R’s own, attach = TRUE would also attach them with library(), and lockfile = "path/to/renv.lock" takes the versions from a lockfile, which suits a blog where each post keeps the lockfile of the day it was written. repos = NULL installs only from the cache (renv 1.2.0). The documentation notes that use() is inspired in part by the groundhog package. The script below runs without a project; R6 2.6.1 is in the cache, so the package is linked and not downloaded.

Source: R documentation: Startup

Source: renv package documentation: embed and use

renv::embed() writes the call for you. Given a script, an R Markdown file or a Quarto document, it inspects the dependencies, finds the versions in the project’s lockfile (or from the installed packages, with lockfile = FALSE, or from the repositories, with lockfile = NA), and inserts a renv::use() call at the top. Only packages that are in the lockfile are included: renv 1.1.6 made embed() stop when a dependency is not available, and 1.2.0 made it warn when a dependency is missing from the lockfile. The call in the output also lists renv itself. The script below works on a file in the temporary directory, because embed() changes the file.

Source: renv package documentation: embed and use

Two mechanisms change how renv behaves. Settings belong to the project, are written to renv/settings.json and travel with the code; config options belong to the user or the machine. The settings are read and written with a function per setting, renv::settings$snapshot.type() to read and renv::settings$snapshot.type("explicit") to write; the value is saved straight away (persist = FALSE keeps a change to the session), and a hand edit of the file needs a restart of R. The defaults for new projects come from options(renv.settings = list(snapshot.type = "all")) or options(renv.settings.snapshot.type = "all"), typically in a user’s ~/.Rprofile. Config options are read with renv::config$name(). For a given name, an R option renv.config.<name> wins; otherwise the environment variable RENV_CONFIG_<NAME> is used, with periods turned into underscores; otherwise the default applies. The environment variable is inherited by child processes and the R option is not, which is the reason to pick one over the other. Config is best set in ~/.Renviron or the site’s Renviron.site; in a project .Rprofile it must come before source("renv/activate.R").

Source: renv package documentation: config

The settings that matter most, with their defaults:

Source: renv package documentation: settings

And a selection of config options, with their defaults:

Source: renv package documentation: config

Other documented controls exist for downloads: renv uses curl when it can, which supports custom headers, timeouts and retries; the renv.download.override option substitutes R’s own download.file(), the RENV_DOWNLOAD_METHOD variable selects the method, proxies are set with http_proxy and https_proxy or a .curlrc, credentials for private remotes come from GITHUB_PAT, GITLAB_PAT, BITBUCKET_USER and BITBUCKET_PASSWORD or GIT_PAT, GIT_USER and GIT_PASSWORD, and renv.download.trace = TRUE prints raw requests while debugging. Keep such secrets in .Renviron, outside the repository.

The recipe in the CI article has three steps: take renv.lock from version control (it was made on a developer’s computer by snapshot()), renv::restore() on the CI service, and cache both the project library and the global cache between runs. The article notes that this is generally not a good fit for CRAN packages, whose checks should see the latest versions of the dependencies. For GitHub Actions the r-lib organisation provides an action, setup-renv, that installs renv, configures the GitHub cache, activates an optional profile, and runs renv::restore(); after it, steps that run R use the project’s library by default.

Source: renv package documentation: Using renv with continuous integration

The same article shows the do-it-yourself version, which uses actions/cache keyed on a hash of the lockfile so that the cache is renewed exactly when the lockfile changes:

Source: renv package documentation: Using renv with continuous integration

Both are fragments that were not run here. The article gives a GitLab CI template in the same spirit, with RENV_PATHS_ROOT set below the project directory and cached. Two newer functions help in pipelines: renv::plan() writes a lockfile from repository metadata without installing, which suits a lightweight container without compilers, and renv::retrieve() downloads packages in one stage so that a later stage installs from the cache. Testing a package in CI is on Testing with testthat, and the Docker pages cover the general side of Docker CI/CD with GitHub Actions.

A container fixes what renv cannot: the operating system, the system libraries, the compilers and the BLAS. The renv Docker article describes the most common case, an existing renv project that is to be built into an image, and the recommended structure is to copy the renv metadata first, restore, and only then copy the rest of the project, so that Docker’s layer cache is reused whenever the code changes and the lockfile does not (the same ordering rule as on Dockerfile Fundamentals and Build Cache and Multi-Stage Builds). The article uses a placeholder for the parent image and recommends a version-tagged one. Here it is rocker/r-ver:4.6.1, the rocker project’s image for R 4.6.1, which is described in the section on pinning R.

Source: renv package documentation: Using renv with Docker

The article’s fragment ends at COPY . .; the CMD line is added here. R -s -e runs R with the input not echoed and executes the expression, then exits (R --help shows both options). renv does not have to be installed in the parent image: R sources .Rprofile, which sources renv/activate.R, which downloads and installs renv. A .dockerignore keeps the host’s library, sandbox and other working directories out of the build context, and lets through the two files the Dockerfile copies:

Source: renv package documentation: Using renv with Docker

RENV_PATHS_LIBRARY before the restore places the library somewhere else, such as /renv/library. To avoid downloading and building packages again when the restore layer is rebuilt, the article describes a BuildKit cache mount. The RUN --mount=type=cache line makes a persistent build cache available at the cache path during the instruction. The symlink setting is the detail that is easy to miss: the mount does not exist in the final image, so links into it would be broken there, and RENV_CONFIG_CACHE_SYMLINKS=FALSE makes renv copy.

Source: renv package documentation: Using renv with Docker

That cache helps on the machine or builder that holds it and, as the article says, will not usually carry over to a fresh CI runner; for that case it describes a bind-mounted host cache restored by the CI platform and given to docker buildx build with --build-context renv-cache=.cache/renv. Compiled packages need system libraries before the restore. renv::sysreqs(distro = "ubuntu:24.04", report = TRUE, collapse = TRUE) reports the apt-get command for the packages in the lockfile (since renv 1.3.1 it works from renv.lock alone, even before any R package is installed), and it should be run again whenever the lockfile changes, since requirements belong to a package version. A multi-stage build keeps compilers out of the final image. The Docker side of this is on Images, Layers and Tags and Docker.

The lockfile records the version of R; renv cannot select it. renv::status() compares the two, and the script shows the message by pointing it at a copy of the lockfile that claims R 4.5.2. The r.version setting is the knob for projects where several people use different R versions, and the load-time check warns when the major and minor version differ. This status message appeared in renv 1.0.4. What snapshot() does is overwrite the recorded version with the running one, so changing R and snapshotting is the way to declare a deliberate upgrade.

Source: renv package documentation: status

To choose the R version on a computer, the renv documentation points at tools such as rig. rig is a community tool, a standalone program for macOS, Windows and Linux that installs and manages several versions of R side by side and switches the default for the terminal and the IDEs; its version at the time of writing is 0.11.0. The commands below install R 4.6.1, make it the default and list the versions. They are a fragment that was not run here, and rig is not an official R tool. rig is also described as able to import and export an renv.lock in its experimental rig proj feature.

Source: rig (community tool): README

For a reproducible machine rather than a reproducible R, the usual answer is a container. The rocker project’s rocker/r-ver images are described as an alternative to the Debian-based r-base image with an emphasis on reproducibility. Its page lists what that means. The images build on an LTS release of a Linux distribution chosen when the R version was released; they install a fixed version of R from source rather than whatever the distribution packages; and they set Posit Public Package Manager as the default CRAN mirror, which serves compiled Linux binaries for the amd64 platform. And, for versions of R that are not the latest, they install all R packages from a fixed snapshot of CRAN mirror taken at a given date, which the page says makes the same version of a package install whenever the installation happens. So rocker/r-ver:4.6.1 pins R and the system layer, and, once a newer R exists, the CRAN snapshot that plain install.packages() uses by default. The 4.6.1 image used for checking this page reported R 4.6.1 and had the package manager’s latest address as its default repository, not a dated snapshot, which fits the statement that only the images that are not the latest are frozen; the page does not list the snapshot date of each version. The same page shows how to change the mirror in an image by writing a new options(repos = ...) line into Rprofile.site. Combined with renv, the two layers pin different things: the base image fixes R and system libraries, and the lockfile fixes the packages, whatever the mirror says. The Dockerfile earlier on this page does exactly that: the tag in its FROM line is the pin of R.

Source: rocker project: the r-ver images

Before renv there was packrat, which also gave a project a private library and a snapshot, with a packrat/ directory and a packrat.lock file. Its repository now says that packrat has been soft-deprecated and is superseded by renv, that it will continue to be maintained while all new development focuses on renv, and that renv::migrate() migrates a project from packrat to renv. migrate() can move the lockfile (packrat/packrat.lock to renv.lock), the sources, the library, compatible options and the cache; the packrat argument selects the components. A project that still uses packrat is a candidate for renv::migrate() followed by renv::status(). The rest of this page applies to the result. The block below is a fragment that was not run, because there is no packrat project in the examples to migrate.

Source: renv package documentation: migrate

The messages that renv prints are part of its interface, and most are a call to action. This script collects the ones that have not appeared yet: a restore in a directory that has no lockfile, a status in one that never used renv, a lockfile that is not JSON, and an install of a package that does not exist (this one queries the repository, so it needs the network). The error from install() is a condition that can be caught, and its message lists the failures.

Source: renv package documentation: restore

Here are the other messages of this page in one place, with the usual remedy. The first group is printed by status().

Source: renv package documentation: status

The first line is the goal. The second asks for restore() (recorded) or install() (not recorded). The third and fourth ask for snapshot() or restore(), depending on which side is right. The fifth asks for the right R, or for a snapshot to record the R in use. The sixth asks for init(). The second group belongs to snapshot() and restore():

Source: renv package documentation: snapshot

The messages with "will be updated in the lockfile" list package, old and new version in the form [* -> 2.0.0], and the ones that are "already" something say there is nothing to do. The remaining two are failures that stop the work: "Failed to parse 'renv.lock'" followed by the position, which means the file was damaged, for example by a bad merge, so restore it from version control; and "package installation failed", which lists the packages that did not install, usually with a reason such as "is not available". When a restore fails because a package from an old lockfile no longer builds, restore(retry = TRUE) tries the latest version of the failing packages.

The introduction describes two levels. renv::deactivate() removes the autoloader line from .Rprofile and leaves the other renv files alone, so that renv::activate() brings it back; renv::deactivate(clean = TRUE) removes the lockfile and the renv/ directory too, leaving the project as it was found. In an interactive session both restart R; in a script the change is for the next session. The script below deactivates the project and activates it again. It is the last script, because after deactivate() the project is not active in this session.

Source: renv package documentation: activate and deactivate

To stop using renv for all projects, delete renv’s global state, which is the root directory given by renv::paths$root(), and then remove the package. The block below is a fragment that was not run, and it is destructive: it deletes the cache of every renv project on the machine.

Source: renv package documentation: Introduction to renv

The environment variable RENV_CONFIG_AUTOLOADER_ENABLED=FALSE is the way to turn the autoloader off for one session without changing any file.

The renv NEWS file lists every release. The ones that changed what this page describes follow, each with the CRAN release date given in the NEWS.

Source: renv package documentation: NEWS

The 1.0.0 release is the first one numbered 1.x, after the 0.x releases that began with the initial CRAN release, and the 1.x line is the one all of this page applies to. The behaviour of 1.1, 1.2 and 1.3 is mostly additive; the largest visible change is the lockfile format of 1.1.0. renv needs no particular release of R for what this page shows; the one R-version fact is that the automatic operating-system prefix of library and cache paths is the default from R 4.4.0 on.

Material about renv written before 2023, and material about its predecessors, differs from the current tool in the following ways.

Source: renv package documentation: NEWS