{renv}: Easy Start

This page provides the basic steps to starting a project with the {renv} package, and how to update the renv.lock file as you add new packages to your project. This page will be followed by a more detailed explanation of the package’s functionality in the Starting Details page.

Initiating {renv}

When using or adding {renv} to one of your projects, you will likely enter from one of two approaches: either from a new project with RStudio, or by adding {renv} to an already existing (or non-RStudio) project.

Either approach should yield the following results in the directory you’re working within:

  • Creation of a renv.lock file and a renv folder
  • Creation of or additions to the .Rbuildignore and .Rprofile files
  • A renv folder will be created in the project directory (for {renv} version 1.0.0 and above)

For most purposes, one will only need to have a passing understanding of the renv.lock file which records the packages used in the project and their versions. The renv folder is where the packages are stored, and the .Rbuildignore and .Rprofile files are used to ensure that the project is reproducible and that the correct packages are loaded when the project is opened.

Git and renv Notice

The renv folder comes with a .gitignore file. This file should be respected if you are using git with your project–do not override or force track items in the renv folder. A more detailed explanation is available in the Advanced Topics section, but TL;DR: the project library should always be rebuilt from the renv.lock file.

With a New RStudio Project

When initiating a new project from within RStudio such as a typical .Rproj, a Quarto website, a new R package or similar, you can follow the approximate directions below to check the box that you would like to “Use renv with your project.”

  1. File
  2. New Project
  3. New Directory
  4. New Project
  5. [x] Use renv with this project

From an Existing Project or Folder

In essentially all other scenarios, one can initiate {renv} for a project by navigating to your project/folder and running the two commands below.

install.packages("renv")

library(renv)
init()

Check Status of Project

After initiating {renv} in your project, you should see a message indicating that your project is in a “consistent state.” In short, this means that {renv} has detected the following:

  • That all packages detected in the project are listed in the renv.lock file
  • That all packages in the renv.lock file are actually installed in the project
  • That all installed packages are the correct version

As you further develop your project, the packages you use may change or you may not have all required packages downloaded (particularly if you’re collaborating with others). You can check the status of your project at any time by running the renv::status() function.

status()

If your project is in a consistent state, you will see the following message:

The project is already in a consistent state.

If your project is not in a consistent state, you will see a message indicating what is wrong with the project, and a potential remedy for the inconsistent state. For example, if you have a package that is not listed in the renv.lock file, you will see a message like the following:

The project is out of sync with the lockfile.
- Packages that are not in the lockfile:
    - {package_name}

Updating renv.lock

As you write additional .R, .Rmd, and/or .qmd files for your project, you will presumably employ more and more functions from foreign packages, and these new packages should be captured in the renv.lock file. This can be done by “snapshotting” the project which will initiate a search for calls to library(), require() and namespaced calls to functions e.g. package::function().

snapshot()

Running the snapshot() function will capture new packages used in your project, and it will update the package versions in the renv.lock file if you have installed new versions to the project you are working in.

This is essentially 80% of the work you will ever need to put into creating a project that also uses {renv}. The other major component of using this package will be “restoring” libraries for either your own projects or for projects shared by others using renv::restore(). This is discussed next in Restoring A Project, but we strongly recommend reading the details of Understanding {renv} first.

Back to top