For a package to be recorded in the lockfile, it must be both:
Installed your project library, and
Used by the project, as determined by
renv::dependencies().
This ensures that only the packages you truly require for your
project will enter the lockfile; development dependencies
(e.g. devtools) normally should not.
So if you find a package is not entering the lockfile, check the
output of renv::dependencies(). If an expected package is
not listed, it’s likely because dependencies() uses static
analysis and does not understand all of the different ways in which a
package might be used in a project. See the docs for more details.
If you’d instead prefer to capture all packages installed into your project library (and eschew dependency discovery altogether), you can do so with:
Packages can also be explicitly ignored through a project setting, e.g. with:
You might also want to double-check the set of ignored packages
(renv::settings$ignored.packages()) and confirm that you
aren’t unintentionally ignoring a package you actually require.
See the documentation in ?snapshot for more details.
If you’d like to explicitly declare which packages your project depends on, you can do so by telling renv to form “explicit” snapshots:
In this mode, renv will only include packages which are explicitly
listed in the project’s DESCRIPTION file as
dependencies.
The most important thing to remember is that
renv::snapshot() captures the state of your project at the
point in time when renv::snapshot() was called. In that
sense, the “right” way to update the lockfile is to:
options(repos = <...>); …renv::snapshot() to update the lockfile.That said, you are also free to modify the renv.lock
lockfile by hand if necessary; e.g. if you want to manually add / change
repositories, change the version of a package used, and so on. The
renv.lock lockfile is a JSON file. A JSON schema is provided in the renv
repository.
The main downside to editing a package record in the lockfile
directly is that you won’t be able to provide a Hash for
that package, and so renv won’t be able to use its global package cache
when installing that package.
This is related to the above question: by design,
renv.lock normally only captures build-time or deploy-time
dependencies; it may not capture the packages that you use in iterative
workflows (e.g. devtools). However, you may want some way
of still ensuring these development dependencies get installed when
trying to restore a project library.
For cases like these, we recommend tracking these packages in a
project DESCRIPTION file; typically, within the Suggests:
field. Then, you can execute:
to request that renv install the packages as described in the
DESCRIPTION file. In addition, the Remotes: fields will be
parsed and used, to ensure packages are installed from their declared
remote source as appropriate.
Suppose you were using renv to manage an older project’s dependencies. You have an older lockfile, capturing the dependencies in use when you were last working with that project. You now need to resume work on this project – what do you do?
The answer depends on how exactly you want to use the project. Do you want to treat it as a “time capsule”, with dependencies frozen in time? Or are the dependencies in this project fluid, and you are primarily using renv just for isolation of project dependencies?
For time capsules, use renv::restore() to reinstall the
exact packages as declared in the project lockfile
renv.lock. You may also need to find and install the older
version of R used previously with that project, unless your intention is
to upgrade R.
For projects with fluid dependencies, call
renv::update() to get the latest versions of the
dependencies. Once you’ve verified that the code still works (or made
the changes needed to get it working), call
renv::snapshot() to record the latest versions.
You can also take a more managed approach, that’s somewhat in between the two extremes:
Use renv::restore() to restore the project state as
defined in the lockfile.
Install and update packages deliberately with
renv::install() and friends.
Verify your code works, then call renv::snapshot()
to update the new lockfile.
Some issues ultimately boil down to a lack of connectivity between
your machine and the R package repositories and remote sources you are
trying to use. If you are working in a corporate environment, it may be
worth confirming whether you have a corporate proxy in place inhibiting
internet access, or whether R and renv need to be configured in a way
compatible with your working environment. This is often true on Windows
machines in enterprise environments, where the default “wininet”
download method may work more reliably than others. Learn more in
vignette("package-install").
In addition, note that renv places shims on the R search path that
re-routes calls from install.packages() to
renv::install(). If you need to bypass these shims, you can
use utils::install.packages(<...>); that is, with the
call to install.packages() explicitly qualified with the
package utils::. See ?renv::load more
details.