Restoring Another Project

The discussion so far on using {renv} has been about initiating a project with {renv} and then updating the renv.lock file as you work on the project. This is generally the more complicated portion of the work you will ever need to do with {renv}. The other side of using {renv} is restoring a project that someone else has shared with you or restoring a project that you have shared with others. This is the topic of this page.

We will cover restoring a project from a GitHub repository, restoring a project from a lockfile, and restoring a project after upgrading R.

When to restore()

From a GitHub Repo

Restoring a project library from a GitHub repository is the most straightforward method to restore a project. A repo should always have all of the required files for restoring a project including the renv.lock file, the renv folder, the *.Rproj file, and the R scripts. Note that repos generally do not (and should not) contain the renv/library folder–this is intended behavior. The renv/library contains “symlinks” to the actual package files on your machine, and these symlinks are not portable across machines1. Moreover, the renv/library folder can be quite large and is not necessary for restoring a project.

The steps for restoring a project from a GitHub repository are as follows:

  • Clone the repository to your local machine with git clone
  • Open the *.Rproj file
  • Run renv::restore()

There should not be anything else to do! The renv.lock file will be used to install the correct versions of the packages you need for the project.

From a lockfile

You may encounter situations where it’s not practical or possible to use a GitHub repository for your project, namely if your collaborators are not familiar with using GitHub. In these cases, you can both restore and share a project’s depedencies using just the renv.lock file. This procedure for restoring contains just a few extra steps compared to the previous method, but should still look familiar:

  • Obtain the renv.lock file from your collaborators.
  • Place the renv.lock in the same directory as your project’s *.Rproj file.
  • Run renv::status(). The results will look similar to this:
renv::status()
#> This project does not appear to be using renv.
#> Use `renv::restore()` to install the packages defined in lockfile.
  • Option 1: Run renv::restore(). If prompted, choose the option “Activate the project and use the project library.” This will create all other necessary files and directories for a {renv} project.
  • Option 2: Run renv::init(). Choose the option to “Restore the project from the lockfile.” This will do everything that renv::restore() does and install the packages at the same time.

After Upgrading R

Something that may come as a surprise is the need to restore a project after upgrading R. This occurs because the {renv} package creates a separate cache for each major and minor version of R that you use. A more detailed explanation of this can be found in the caching chapter, but a summarized version is also provided here.

To first clarify “major” and “minor” upgrades: they refer to semantic versioning of software which is a way of providing version numbers to software using three numbers separated by periods: major.minor.patch. For example, an upgrade from R4.3.2 to 4.3.3. is a “patch” while an upgrade from R4.3 to R4.4 is a “minor” release. Minor releases occur approximately once per year, and, after installing a new minor release, you will need to restore your project.

If you install a new major or minor version of R, you will need to ensure that the version of R you are using is compatible with your project(s). There are two ways to achieve this:

The first option is to update your project to use the new version of R. This can be done by running renv::update() to update the packages in your project (particularly the base R packages that came with the new version of R), and then running renv::snapshot() to update the renv.lock file.

The second option is to switch between R versions using a tool like rswitch or rig. These tools are useful if you are working on multiple projects that require different versions of R, or if you have projects where it’s not possible to update the version of R being used.

When to upgrade() and update()

If you are working on a project and you want to update the packages in your project, you can run renv::update(). This will update the packages in your project to the latest versions that are compatible with the versions of the packages in your renv.lock file. If you want to update a specific package, you can run renv::update("package_name").

If you want to update the renv package itself, you can run renv::upgrade(). This will update the renv package to the latest version available on CRAN.

Back to top

Footnotes

  1. See the Caching chapter for more information on the renv/library folder.↩︎