All use of Scientific Computing and Data resources in publications and presentations must acknowledge Mount Sinai’s CTSA funding award. Click here

Scientific Computing and Data / High Performance Computing / Documentation / renv

Reproducible R Environments with renv

Contents
Overview of renv
Usage

 

Overview of renv

renv is an R package designed to help you manage project-specific libraries in a reproducible and isolated way. It creates a dedicated environment for each project, ensuring that the exact package versions used are recorded and can be restored later. This makes it easier to share code, collaborate with others, and reproduce results across different systems. By using renv, you avoid conflicts between projects and maintain consistency in your R workflows.

Key Features of renv

  • Project Isolation – Creates a separate library for each project, preventing package conflicts across projects.
  • Reproducibility – Captures exact package versions in a lockfile (renv.lock) so environments can be restored reliably.
  • Easy Environment Restore – Reinstalls all dependencies with a single command (renv::restore()), ensuring consistency across systems.
  • Lightweight Dependency Management – Only installs packages actually used in the project, reducing unnecessary overhead.
  • Integration with Version Control – Works seamlessly with Git by tracking the lockfile while ignoring local libraries.
  • Automatic Dependency Detection – Scans project files to identify required packages.
  • Caching for Efficiency – Uses a global cache to speed up installations and reduce disk usage.
  • Cross-Platform Consistency – Helps reproduce environments across different machines (local, HPC, cloud).
  • Minimal Workflow Changes – Fits naturally into existing R workflows with simple commands like init(), snapshot(), and restore().

Usage

1. Initializing a Project

To start using renv in a new or existing project, run:

renv::init()

What this does:

  • Creates a project library: a private folder for project-specific packages
  • Generates an renv.lock file: records exact package versions for reproducibility
  • Adds an .Rprofile file: automatically activates the environment when the project is opened

2. Activating an Existing Project Environment

If renv is already set up but not active in your session:

renv::activate()

What this does:

  • Switches the session to use the project-specific library
  • Ensures all package operations happen inside the isolated environment
  • Useful when switching projects or working on HPC systems where auto-activation may not occur

3. Installing Packages

Note: To enable internet access for package installation on a compute node, please run the following code in the R console.

Sys.setenv(http_proxy="http://proxy.chimera.hpc.mssm.edu:3128")
Sys.setenv(https_proxy="http://proxy.chimera.hpc.mssm.edu:3128")
Sys.setenv(all_proxy="http://proxy.chimera.hpc.mssm.edu:3128")
Sys.setenv(no_proxy="localhost,*.hpc.mssm.edu,*.chimera.hpc.mssm.edu,172.28.0.0/16") 

Within an renv project, to install the latest version of a package:

install.packages("pkg")
renv::install("pkg")

Package Specification Options

Repository Command
Specific CRAN version renv::install("pkg@1.2.3")
Latest version (force update) renv::install("pkg") or renv::update("pkg")
GitHub specific commit / tag renv::install("username/repo@commit_hash") or username/repo@v1.2.3
Bioconductor specific version renv::install("bioc::DESeq2") (or with version via BiocManager renv::settings$bioconductor.version("version"))
Force reinstall / rebuild renv::install("pkg@1.2.3", rebuild = TRUE)

What this does:

  • Provides different ways to specify where packages come from and which version to install
  • Supports installing specific CRAN versions, latest versions, GitHub commits/tags, and Bioconductor packages
  • Enables precise control over package sources to ensure reproducible and consistent environments

4. Snapshotting the Environment

After installing or updating packages, you record the environment state using:

Basic snapshot

renv::snapshot()

Full snapshot

renv::snapshot(type = "all")

Key difference:

Feature type = “implicit” (Default) type = “all”
Primary Source Your code files (.R, .Rmd) Your library folder (renv/library)
Cleanliness High (only used packages) Low (contains everything installed)
Reliability Good (but can miss hidden dependencies) Perfect (captures everything present)
Use Case Most standard data science projects. Complex production environments or “sealed” snapshots.

What this does:

  • Saves the current R project’s package environment into renv.lock for reproducibility
  • Records exact package versions used in the project
  • Allows restoring the same environment later with renv::restore()

5. Reproducing Environments from renv.lock

To reproduce the environment elsewhere:

renv::restore()

What this does:

  • Reads renv.lock
  • Installs exact package versions
  • Recreates the project library

6. Package Management Tools

Command Purpose
renv::status() Check consistency between library and lockfile
renv::update() Update installed packages
renv::clean() Remove unused packages
renv::paths$library() Show project library location

7. Reproducibility Scope

renv ensures reproducibility of R package environments, but does not manage:

  • R version itself
  • System-level libraries (OS dependencies)
  • External tools (e.g., Pandoc, compilers)

8. Summary

renv enables reproducible R environments by locking and restoring package versions across systems.

The key idea:

Use snapshot() for clean dependency tracking, and snapshot(type = "all") when you need a complete environment freeze.

9. Additional Resources