Insert the following code to your .Rprofile file: options(renv.download.override = utils::download.file). Certify that renv is activated (renv::activate()). 2.1 (optional) Delete all packages, except for renv, installed in ./renv/library. Reinstall renv with its dependencies with utils::install.packages(“renv”, dependencies = TRUE). Restart R (.rs.restartR()). Try to install a package using renv::install() (e.g., renv::install(“dplyr”)). Also, don’t forget to read renv’s _ Alternative downloaders_ section: https://rstudio.github.io/renv/articles/package-install.html#alternative-downloaders .

How-To Guide: Setting Up a Quarto Project with renv on a New Computer (macOS & Windows)

This guide will walk you through the steps to get your Quarto project, complete with its isolated renv package environment, up and running on a fresh machine.

Prerequisites: What You Need to Install First

Before you touch your project, you need the core software installed.

  1. Install R
    • macOS: Download the latest version from CRAN.
    • Windows: Download the latest version from CRAN.
    • Tip: If your project requires a specific R version, you can download historical versions from the CRAN archives.
  2. Install RStudio (Highly Recommended)
    • Download the RStudio Desktop (Free) version from RStudio.com. This is the easiest way to manage your project.
    • This step is optional but highly recommended for a smoother experience.
  3. Install Quarto
    • Quarto is a separate command-line tool. Download and run the installer from Quarto.org.
    • Verification: Open your system’s terminal (macOS) or Command Prompt/PowerShell (Windows) and type quarto check. This will confirm Quarto, R, and necessary packages are correctly detected.
  4. Install the renv package (in R)
    • Open RStudio (or just the R application).
    • Run this command in the R console: r install.packages("renv")

Step-by-Step: Restoring Your Project

Now that the basics are installed, it’s time to work on your specific project.

  1. Get Your Project Files
    • Transfer your entire project folder (the one containing the .Rproj, _quarto.yml, renv.lock, and .Rprofile files) to your new computer. You can use a USB drive, cloud storage (Dropbox, Google Drive), or version control (GitHub, GitLab).
  2. Open the Project
    • The Easy Way (Using RStudio):
      • Double-click the .RProj file in your project folder. This will automatically open RStudio and set the correct working directory.
      • RStudio will likely detect the renv environment and show you a prompt asking if you want to activate it. Click “Yes”.
    • The Manual Way (Terminal/Command Prompt):
      • Open your terminal (macOS) or Command Prompt (Windows).
      • Navigate to your project directory using the cd command.
      • Example for Windows: cd C:\Users\YourName\Documents\My_Quarto_Project
      • Example for macOS: cd ~/Documents/My_Quarto_Project
  3. Restore the Packages
    • With your project open in RStudio, the console should already be ready.
    • Run the following command to install all the packages exactly as they were in the original project (versions and all): r renv::restore()
    • This will read the renv.lock file and start downloading and installing all the necessary packages from CRAN. This process can take a few minutes.
  4. What if the automatic activation didn’t happen?
    • If you’re not using RStudio or the prompt didn’t appear, you can manually activate and restore renv.
    • In your R console (within the project directory), run: r renv::activate() # Ensures the project uses its private library renv::restore() # Installs the packages

Testing and Final Steps

  1. Render Your Project

    • From RStudio: Click the “Render” button in the script editor while any .qmd file is open.
    • From the Terminal: Navigate to your project directory and run: bash quarto render # or render a specific file quarto render my_report.qmd
    • If it renders successfully, congratulations! Your environment is set up correctly.

  2. Troubleshooting Common Issues

    • “Package not available” or download errors:
      • Check your internet connection.
      • Try specifying the CRAN repository in the restore command: r renv::restore(repos = "https://cloud.r-project.org")
    • System Dependency Errors (e.g., sf, curl, V8):
      • Some R packages require software outside of R.
      • macOS: The easiest fix is to install Homebrew, then run brew install geos gdal. The error message will usually tell you what’s missing (libgit2, pandoc, etc.).
      • Windows: The rtools toolchain that comes with R usually handles this. Ensure you selected “Install RTools” during the R installation. If a specific library is missing, you may need to download it manually (this is rarer on Windows for common packages).
    • R Version Mismatch:
      • renv will warn you if the current R version doesn’t match the one used to create the lockfile. You can often proceed anyway with renv::restore(), but be aware of potential compatibility issues.

Summary Checklist

You should now have a perfectly replicated development environment on your new machine!

Back to top