manage-renv-dependencies

Manage renv Dependencies

Set up and maintain reproducible R package environments using renv.

When to Use

• Initializing dependency management for a new R project
• Adding or updating package dependencies
• Restoring a project environment on a new machine
• Troubleshooting renv restore failures
• Integrating renv with CI/CD pipelines

Inputs

• Required: R project directory
• Optional: Existing renv.lock file (for restore)
• Optional: GitHub PAT for private packages

Procedure

Step 1: Initialize renv

renv::init()

This creates:

• renv/ directory (library, settings, activation script)
• renv.lock (dependency snapshot)
• Updates .Rprofile to activate renv on load

Expected: Project-local library created. renv/ directory and renv.lock present. .Rprofile updated with activation script.

On failure: If it hangs, check network connectivity. If it fails on a specific package, install that package manually first with install.packages() and then rerun renv::init().

Step 2: Add Dependencies

Install packages as usual:

install.packages("dplyr")
renv::install("github-user/private-pkg")

Then snapshot to record the state:

renv::snapshot()

Expected: renv.lock updated with new packages and their versions. renv::status() shows no out-of-sync packages.

On failure: If renv::snapshot() reports validation errors, run renv::dependencies() to check which packages are actually used, then renv::snapshot(force = TRUE) to bypass validation.

Step 3: Restore on Another Machine

renv::restore()

Expected: All packages installed at the exact versions in renv.lock.

On failure: Common issues: GitHub packages fail (set GITHUB_PAT in .Renviron), system dependencies missing (install with apt-get on Linux), timeouts on large packages (set options(timeout = 600) before restore), or binaries not available (renv compiles from source; ensure build tools are installed).

Step 4: Update Dependencies

# Update a specific package
renv::update("dplyr")

# Update all packages
renv::update()

# Snapshot after updates
renv::snapshot()

Expected: Target packages are updated to their latest compatible versions. renv.lock reflects the new versions after snapshot.

On failure: If renv::update() fails for a specific package, try installing it directly with renv::install("package@version") and then snapshot.

Step 5: Check Status

renv::status()

Expected: "No issues found" or a clear list of out-of-sync packages with actionable guidance.

On failure: If status reports packages used but not recorded, run renv::snapshot(). If packages are recorded but not installed, run renv::restore().

Step 6: Configure .Rprofile for Conditional Activation

if (file.exists("renv/activate.R")) {
  source("renv/activate.R")
}

This ensures the project works even if renv isn't installed (CI environments, collaborators).

Expected: R sessions activate renv automatically when starting in the project directory. Sessions without renv installed still start without errors.

On failure: If .Rprofile causes errors, ensure the file.exists() guard is present. Never call source("renv/activate.R") unconditionally.

Step 7: Git Configuration

Track these files:

renv.lock           # Always commit
renv/activate.R     # Always commit
renv/settings.json  # Always commit
.Rprofile           # Commit (contains renv activation)

Ignore these (already in renv's .gitignore):

renv/library/       # Machine-specific
renv/staging/       # Temporary
renv/cache/         # Machine-specific cache

Expected: renv.lock, renv/activate.R, and renv/settings.json are tracked by Git. Machine-specific directories (renv/library/, renv/cache/) are ignored.

On failure: If renv/library/ accidentally gets committed, remove it with git rm -r --cached renv/library/ and add it to .gitignore.

Step 8: CI/CD Integration

In GitHub Actions, use the renv cache action:

- uses: r-lib/actions/setup-renv@v2

This automatically restores from renv.lock with caching.

Expected: CI pipeline restores packages from renv.lock with caching enabled. Subsequent runs are faster due to cached packages.

On failure: If CI restore fails, check that renv.lock is committed and up to date. For private GitHub packages, ensure GITHUB_PAT is set as a repository secret.

Validation

• renv::status() reports no issues
• renv.lock is committed to version control
• renv::restore() works on a clean checkout
• .Rprofile conditionally activates renv
• CI/CD uses renv.lock for dependency resolution

Common Pitfalls

• Running renv::init() in wrong directory: Always verify getwd() first
• Mixing renv and system library: After renv::init(), only use the project library
• Forgetting to snapshot: After installing packages, always run renv::snapshot()
• --vanilla flag: Rscript --vanilla skips .Rprofile, so renv won't activate
• Large lock files in diffs: Normal — renv.lock is designed to be diffable JSON
• Bioconductor packages: Use renv::install("bioc::PackageName") and ensure BiocManager is configured

Related Skills

• create-r-package - includes renv initialization
• setup-github-actions-ci - CI integration with renv
• submit-to-cran - dependency management for CRAN packages