Restore project library from a lockfile

Restore a project's dependencies from a lockfile, as previously generated by snapshot().

restore(
  project = NULL,
  ...,
  library = NULL,
  lockfile = NULL,
  packages = NULL,
  exclude = NULL,
  rebuild = FALSE,
  repos = NULL,
  clean = FALSE,
  transactional = NULL,
  prompt = interactive()
)

Arguments

project

The project directory. If NULL, then the active project will be used. If no project is currently active, then the current working directory is used instead.

...

Unused arguments, reserved for future expansion. If any arguments are matched to ..., renv will signal an error.

library

The library paths to be used during restore.

lockfile

Path to a lockfile. When NULL (the default), the renv.lock located in the root of the current project will be used.

packages

A subset of packages recorded in the lockfile to restore. When NULL (the default), all packages available in the lockfile will be restored. Any required recursive dependencies of the requested packages will be restored as well.

exclude

A subset of packages to be excluded during restore. This can be useful for when you'd like to restore all but a subset of packages from a lockfile. Note that if you attempt to exclude a package which is required as the recursive dependency of another package, your request will be ignored.

rebuild

Force packages to be rebuilt, thereby bypassing any installed versions of the package available in the cache? This can either be a boolean (indicating that all installed packages should be rebuilt), or a vector of package names indicating which packages should be rebuilt.

repos

The repositories to use when restoring packages installed from CRAN or a CRAN-like repository. By default, the repositories recorded in the lockfile will be used, ensuring that (e.g.) CRAN packages are re-installed from the same CRAN mirror.

Use repos = getOption("repos") to override with the repositories set in the current session, or see the repos.override option in config for an alternate way override.

clean

Boolean; remove packages not recorded in the lockfile from the target library? Use clean = TRUE if you'd like the library state to exactly reflect the lockfile contents after restore().

transactional

Whether or not to use a 'transactional' restore. See Transactional Restore for more details. When NULL (the default), the value of the install.transactional config option will be used.

prompt

Boolean; prompt the user before taking any action? For backwards compatibility, confirm is accepted as an alias for prompt.

Value

A named list of package records which were installed by renv.

Details

renv::restore() compares packages recorded in the lockfile to the packages installed in the project library. Where there are differences it resolves them by installing the lockfile-recorded package into the project library. If clean = TRUE, restore() will additionally delete any packages in the project library that don't appear in the lockfile.

Transactional Restore

By default, renv::restore() will perform a 'transactional' restore, wherein the project library is mutated only if all packages within the lockfile are successfully restored. The intention here is to prevent the private library from entering an inconsistent state, if some subset of packages were to install successfully but some other subset of packages did not. renv::restore(transactional = FALSE) can be useful if you're attempting to restore packages from a lockfile, but would like to update or change certain packages piece-meal if they fail to install.

The term 'transactional' here borrows from the parlance of a 'database transaction', where the failure of any intermediate step implies that the whole transaction will be rolled back, so that the state of the database before the transaction was initiated can be preserved. See https://en.wikipedia.org/wiki/Database_transaction for more details.

See also

Other reproducibility: lockfiles, snapshot()

Examples

if (FALSE) { # \dontrun{

# disable automatic snapshots
auto.snapshot <- getOption("renv.config.auto.snapshot")
options(renv.config.auto.snapshot = FALSE)

# initialize a new project (with an empty R library)
renv::init(bare = TRUE)

# install digest 0.6.19
renv::install("digest@0.6.19")

# save library state to lockfile
renv::snapshot()

# remove digest from library
renv::remove("digest")

# check library status
renv::status()

# restore lockfile, thereby reinstalling digest 0.6.19
renv::restore()

# restore automatic snapshots
options(renv.config.auto.snapshot = auto.snapshot)

} # }