Per-Project Libraries with RStudio Projects and renv

The \"it works on my machine\" moment in R

You open a colleague's analysis, run the script, and get a different result or a missing function error. The shared global library on your machine has a newer tidyverse, a different locale, or a package you never installed. The useful takeaway is to stop relying on a global library and give each analysis its own isolated environment. RStudio Projects plus renv makes that the default.

RStudio Projects are .Rproj files that set a working directory, session state and project-specific settings for an analysis. That removes setwd() calls and accidental cross-project contamination. renv, maintained by Posit, builds on that isolation by creating a per-project library and recording exact package versions in renv.lock.

Why per-project beats a shared library

A global library is convenient until it isn't. Updating a package for one project can break another. Collaborators have different install histories. renv uses a global package cache with per-project library links, so disk usage stays modest while each project sees only the packages it declares.

The lockfile renv.lock is JSON and records package names, versions and sources. Restoring from it with renv::restore() recreates the project library from the cache or CRAN/Bioconductor. The project is self-describing: anyone who opens the .Rproj can bootstrap the environment.

A concrete setup you can copy

Create a new RStudio Project from File > New Project > New Directory. Choose a folder you can write to, e.g. ~/projects/. The .Rproj file is created and RStudio will set the working directory to that folder on open.

In the R console inside that project, run:

install.packages(\"renv\")
renv::init()

renv::init() creates an renv/ folder with activation scripts and initializes a private library under the project. Expected check: renv/ appears in the Files pane and .Rprofile is modified to activate renv on start. Risk: running init in the wrong directory creates an unwanted project library.

Install packages as usual. Example:

install.packages(c(\"dplyr\", \"readr\"))

When dependencies are stable, snapshot:

renv::snapshot()

This writes or updates renv.lock. Commit renv.lock and the renv/ activation files to version control. Do not commit the project library folder.

Worked example for a collaborator: they clone the repo, open .Rproj in RStudio, and RStudio sources .Rprofile. renv auto-bootstraps and prompts to restore. Running renv::restore() populates the project library from the lockfile. You can verify the environment by running renv::status() and comparing sessionInfo() package versions to those listed in renv.lock.

Trade-offs and what renv does not pin

renv pins R packages but not the R interpreter version or system libraries such as GDAL, compilers or Java. A lockfile restored on a different OS may need to compile from source, which requires system toolchains. Binary vs source behavior differs across platforms.

Snapshotting records packages renv detects as used. Packages loaded indirectly may be missed unless you explicitly call library() in the session before snapshot or use renv::snapshot(type = \"all\"). Hand-editing renv.lock is risky; prefer snapshot and restore commands.

For full cross-OS reproducibility, pair renv with a container that fixes R and system dependencies. renv is the successor to packrat and should be used for new work.

Actionable closing

Make Projects + renv the default for new analyses. Create the project, init renv, install, snapshot before committing. Check the result with renv::status() and by inspecting that renv.lock lists the packages you expect. When sharing, ask collaborators to open the .Rproj and restore. That removes the shared library as a source of drift.