How to lock and restore R project dependencies with renv

Package changes can make an R project produce different results even when its source files stay unchanged. renv gives each project a private library and records the package versions and installation sources needed to rebuild that library.

The default implicit snapshot discovers dependencies referenced by project files. Keep package imports in scripts, reports, or a project DESCRIPTION file so renv.lock captures the packages that the code actually uses.

Use a disposable project copy for the removal-and-restore test. The test removes only digest from the private project library after the lockfile exists; it does not purge the shared renv cache or change packages in the system library.

1. Change to the R project root.

   $ cd ~/projects/sales-report

   The sample path represents the directory that contains the project source.

2. Create a smoke script that uses a project dependency.

   analysis.R

   library(digest)
   cat(digest("locked-dependencies"), "\n")

3. Initialize an empty renv project library without restarting R.

   $ Rscript -e 'renv::init(bare = TRUE, restart = FALSE)'

   The bare option creates the renv infrastructure without installing dependencies before the project source has been reviewed.

4. Install the dependency into the private project library.

   $ Rscript -e 'renv::install("digest")'

5. Run the smoke script against the private project library.

   $ Rscript analysis.R
   f9b2fe0cad20940b8f2bb758718e523a

6. Record the working project library in renv.lock.

   $ Rscript -e 'renv::snapshot(prompt = FALSE)'
   - The project is out-of-sync -- use `renv::status()` for details.
   The following package(s) will be updated in the lockfile:
   
   # CRAN -----------------------------------------------------------------------
   - digest   [* -> 0.6.39]
   - renv     [* -> 1.2.3]
   
   The version of R recorded in the lockfile will be updated:
   - R        [* -> 4.5.2]
   
   - Lockfile written to "~/projects/sales-report/renv.lock".

   The portable project state consists of renv.lock, .Rprofile, renv/activate.R, renv/settings.json, and the project source. The private renv/library directory is rebuilt locally and normally stays out of version control.

7. Confirm that the lockfile, project source, and private library agree.

   $ Rscript -e 'renv::status()'
   No issues found -- the project is in a consistent state.

8. Remove digest from the disposable project library.

   $ Rscript -e 'renv::remove("digest")'
   - Removing package(s) from project library ...
   Removing package 'digest' ... Done!

   The unchanged renv.lock remains the recovery point for this test.

9. Verify that renv detects the missing dependency.

   $ Rscript -e 'renv::status()'
   - None of the packages recorded in the lockfile are currently installed.
   - Use `renv::restore()` to restore the project library.
   The following package(s) are used in this project, but are not installed:
   - digest
   
   See `?renv::status` for advice on resolving these issues.

10. Restore the private project library from renv.lock.

    $ Rscript -e 'renv::restore(prompt = FALSE)'
    - None of the packages recorded in the lockfile are currently installed.
    - Use `renv::restore()` to restore the project library.
    The following package(s) will be updated:
    
    # CRAN -----------------------------------------------------------------------
    - digest   [* -> 0.6.39]
    
    # Installing packages --------------------------------------------------------
    y digest 0.6.39                            [linked from cache]
    Successfully installed 1 package in 1.9 milliseconds.

    renv::restore() changes the private project library to match renv.lock. An unreviewed lockfile can therefore replace working package versions in a shared or production project.

11. Confirm that the restored library matches the lockfile and project source.

    $ Rscript -e 'renv::status()'
    No issues found -- the project is in a consistent state.

12. Run the smoke script with the restored dependency.

    $ Rscript analysis.R
    f9b2fe0cad20940b8f2bb758718e523a