renv::status() reports issues caused by inconsistencies across the project
lockfile, library, and dependencies(). In general, you should strive to
ensure that status() reports no issues, as this maximizes your chances of
successfully restore()ing the project in the future or on another machine.
renv::load() will report if any issues are detected when starting an
renv project; we recommend resolving these issues before doing any
further work on your project.
See the headings below for specific advice on resolving any issues
revealed by status().
status(
project = NULL,
...,
library = NULL,
lockfile = NULL,
sources = TRUE,
cache = FALSE,
dev = FALSE
)This function is normally called for its side effects, but it invisibly returns a list containing the following components:
library: packages in your library.
lockfile: packages in the lockfile.
synchronized: are the library and lockfile in sync?
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.
The library paths. By default, the library paths associated with the requested project are used.
Path to a lockfile. When NULL (the default), the
renv.lock located in the root of the current project will be used.
Boolean; check that each of the recorded packages have a known installation source? If a package has an unknown source, renv may be unable to restore it.
Boolean; perform diagnostics on the global package cache?
When TRUE, renv will validate that the packages installed into the
cache are installed at the expected + proper locations, and validate the
hashes used for those storage locations.
Boolean; include development dependencies? These packages are typically required when developing the project, but not when running it (i.e. you want them installed when humans are working on the project but not when computers are deploying it).
Development dependencies include packages listed in the Suggests field
of a DESCRIPTION found in the project root, and roxygen2 or devtools if
their use is implied by other project metadata. They also include packages
used in ~/.Rprofile if config$user.profile() is TRUE.
status() first checks that all packages used by the project are installed.
This must be done first because if any packages are missing we can't tell for
sure that a package isn't used; it might be a dependency that we don't know
about. Once you have resolve any installation issues, you'll need to run
status() again to reveal the next set of potential problems.
There are four possibilities for an uninstalled package:
If it's used and recorded, call renv::restore() to install the version
specified in the lockfile.
If it's used and not recorded, call renv::install() to install it
from CRAN or elsewhere.
If it's not used and recorded, call renv::snapshot() to
remove it from the lockfile.
If it's not used and not recorded, there's nothing to do. This the most common state because you only use a small fraction of all available packages in any one project.
If you have multiple packages in an inconsistent state, we recommend
renv::restore(), then renv::install(), then renv::snapshot(), but
that also suggests you should be running status more frequently.
Next we need to ensure that packages are recorded in the lockfile if and
only if they are used by the project. Fixing issues of this nature only
requires calling snapshot() because there are four possibilities for
a package:
If it's used and recorded, it's ok.
If it's used and not recorded, call renv::snapshot() to add it to the
lockfile.
If it's not used but is recorded, call renv::snapshot() to remove
it from the lockfile.
If it's not used and not recorded, it's also ok, as it may be a development dependency.
The final issue to resolve is any inconsistencies between the version of
the package recorded in the lockfile and the version installed in your
library. To fix these issues you'll need to either call renv::restore()
or renv::snapshot():
Call renv::snapshot() if your project code is working. This implies that
the library is correct and you need to update your lockfile.
Call renv::restore() if your project code isn't working. This probably
implies that you have the wrong package versions installed and you need
to restore from known good state in the lockfile.
If you're not sure which case applies, it's generally safer to call
renv::snapshot(). If you want to rollback to an earlier known good
status, see history() and revert().
renv will also notify you if the version of R used when the lockfile was generated, and the version of R currently in use, do not match. In this scenario, you'll need to consider:
Is the version of R recorded in the lockfile correct? If so, you'll want to ensure that version of R is installed and used when working in this project.
Otherwise, you can call renv::snapshot() to update the version of R
recorded in the lockfile, to match the version of R currently in use.
If you'd like to set the version of R recorded in a lockfile independently
of the version of R currently in use, you can set the r.version project
setting -- see settings for more details.
if (FALSE) {
# 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)
}
Run the code above in your browser using DataLab