renv: Lock R Package Versions for Reproducible Research

renv is an R package that gives each R project its own library of packages and records the exact package versions in a lockfile, so a collaborator, reviewer or future you can install the same versions again. Its official introduction describes the core loop as three calls: renv::init() to convert a project, renv::snapshot() to record the packages in use, and renv::restore() to reinstall exactly what was recorded. This guide covers that loop and, less often explained, the renv::status() diagnostic and which files belong in version control.

What renv is used for in research

renv is a dependency management toolkit for R. It creates project-local libraries, saves the state of those libraries to a lockfile, and restores them later (CRAN package description, checked 2026-10-29). In a research setting that means an analysis script can be re-run against the package versions it was written with, rather than whatever versions happen to be installed on the next machine.

Each project gets its own library, so updating a package in one project does not affect any other project. To avoid downloading the same package repeatedly, renv uses a package cache: a package is downloaded once and linked into the project libraries that need it (renv, “Introduction to renv”, checked 2026-10-29).

What renv does not pin

renv records package versions. It does not install a different version of R itself: renv::status() reports when the lockfile was written under a different R version than the one currently running, which is a flag to act on: either use the R version the lockfile recorded, or run renv::snapshot() to record the current one. For a record of the wider computing setup, see the CASRAI guide on reproducibility infrastructure: workflows, containers and code sharing and the dictionary entry for computational environment.

Install or access (official source only)

renv is published on CRAN under the MIT license. On 2026-10-29 CRAN lists version 1.3.1, published 2026-10-06; the maintainer is Kevin Ushey and Posit Software, PBC is listed as copyright holder and funder. Install it like any other CRAN package:

install.packages("renv")

Official documentation: Introduction to renv and the CRAN package page. If you work in RStudio, the CASRAI guide on how to use RStudio covers the environment itself.

Step-by-step: init, snapshot, restore

1. Open the project and start R in its folder. renv works per project, so run the commands with the project as the working directory.
2. Convert the project: renv::init(). This sets up the project library, the lockfile and an .Rprofile. The .Rprofile is run automatically every time you start R in that project, which keeps the project library active.
3. Work as normal. Install and use packages; they go into the project library.
4. Record the state: renv::snapshot(). This updates the lockfile with metadata about the packages currently used in the project library.
5. Share: commit renv.lock, .Rprofile, renv/settings.json and renv/activate.R to version control.
6. Recreate on another machine: open the project, then run renv::restore(). This uses the lockfile metadata to install exactly the same version of every package.

Output and how to read it

The files renv creates

File or folder	What it is	Commit it?
renv.lock	The lockfile, always called renv.lock. It is JSON and records the packages and their versions.	Yes. Collaborators commit it to version control.
.Rprofile	Runs automatically when R starts in the project and keeps the project library active.	Yes, per the renv introduction.
renv/settings.json	Project settings.	Yes, per the renv introduction.
renv/activate.R	Activation script used by the project.	Yes, per the renv introduction.
renv/library	The project library: all packages currently used by the project.	No. It is rebuilt from the lockfile by renv::restore().

Reading renv::status()

renv::status() reports issues caused by inconsistencies across the project lockfile, library and dependencies. It checks in this order, and the documentation gives a different action for each state:

What status finds	What to do
Packages used by the project but not installed	If the lockfile records them, run renv::restore(); if it does not, run renv::install(). A package recorded but no longer used is removed from the lockfile with renv::snapshot().
A package used in code but not recorded in the lockfile, or recorded but no longer used	Run renv::snapshot() to bring the lockfile in line with the project.
Installed versions that differ from the lockfile	If the code works with the installed versions, run renv::snapshot(); if it does not, run renv::restore().
Lockfile written under a different R version than the current one	If the recorded R version is the right one, install and use it for the project; otherwise run renv::snapshot() to record the current version. renv does not change your R installation.

The function invisibly returns a list with the library, the lockfile and a synchronized flag, so scripts can test whether the project is in sync.

Troubleshooting

• The project behaves as if renv is not active. The .Rprofile created by renv::init() must be present and R must be started in the project folder, because that file runs on startup in that project.
• A collaborator gets different results. Run renv::status() first. It reports an out-of-sync lockfile and a lockfile written under a different R version.
• The lockfile is out of date after you added a package. Run renv::snapshot(); status reports packages that are used but not recorded in the lockfile.
• You want to discard local changes. If the code no longer works after updates, renv::restore() returns the library to the lockfile versions.

Free alternatives

Option	How it differs from renv	CASRAI guide
conda / mamba environment files	An environment file records packages for a conda environment, which can include more than R packages.	Sharing a reproducible conda environment; mamba vs conda
Containers and workflow tools	Capture the wider software setup around a project rather than R packages alone.	Reproducibility infrastructure

FAQ

What does renv::snapshot() do?

It updates the lockfile with metadata about the packages currently used in the project library.

What does renv::restore() do?

It uses the lockfile to install exactly the same version of every package it records.

Should renv.lock be committed to Git?

Yes. The lockfile is how collaborators receive the recorded versions. Commit .Rprofile, renv/settings.json and renv/activate.R with it; the project library is rebuilt by restore.

Does renv change my R version?

No. renv::status() reports a mismatch between the R version in the lockfile and the one in use, but R itself is managed separately.

Sources (official docs)

• Posit / renv project, Introduction to renv, checked 2026-10-29 (shows renv 1.3.1).
• Posit / renv project, renv::status() reference, checked 2026-10-29.
• CRAN, renv package page, checked 2026-10-29.