Renv (pronounced "arr env") is a tool for installing multiple versions of R alongside each other.

Why it exists

A new version of R is released every few months, and with each release comes new changes. These changes can make code and packages break or not work in the same way. For ongoing projects, it's a good idea to update your code to work with the new versions, but sometimes you either don't want to or can't do that.

Renv is a tool that helps freeze your R version to alleviate this problem. This tool works with your terminal shell to switch R versions automatically.

How to install it

  1. Download Renv

    The best way to install Renv is to use git. Git is version control software that will let you download new versions of Renv easily.
    git clone ~/.Renv

    If you don't want to use git, you can download a zip of Renv instead. Unzip it in your home folder and rename the Renv directory (called Renv-Renv) to .Renv.

  2. Configure your terminal to use Renv

    Look in your home directory and edit the .bashrc file (for Linux) or the .bash_profile file (for Mac) and add the following to the end:
    export PATH="$HOME/.Renv/bin:$PATH"
    eval "$(Renv init -)"

    Or you can run one of these commands to do it for you:

    echo 'export PATH="$HOME/.Renv/bin:$PATH"' >> ~/.bashrc
    echo 'eval "$(Renv init -)"' >> ~/.bashrc

    echo 'export PATH="$HOME/.Renv/bin:$PATH"' >> ~/.bash_profile
    echo 'eval "$(Renv init -)"' >> ~/.bash_profile

    info You'll need to restart your terminal after doing this.

  3. Install R

    Renv works by having multiple versions of R installed. To install R for Renv, there is an additional tool called R-build to make it easier.

    If you're using git, execute the following commands to install the R-build plugin:
    mkdir -p ~/.Renv/plugins
    git clone git:// ~/.Renv/plugins/R-build

    If you're not using git, first create the plugins folder inside the .Renv folder. Download the R-build zipfile and unzip it in the .Renv/plugins folder. Then rename the R-build directory (called R-build-R-build) to R-build.

    Next, you can install a version of R by running:
    Renv install 2.15.2

    This will take a while.

    After it's done run this command to refresh Renv:
    Renv rehash

    info You may need to install some additional packages to build R. If you're on Ubuntu, run this command: sudo apt-get build-dep r-base

    info If you want to use Renv in combination with RStudio, you need to build R a little differently, like so:

    CONFIGURE_OPTS="--enable-R-shlib" Renv install 2.15.2

    Notice the additional CONFIGURE_OPTS bit. RStudio needs the R shared library in order to work.

How to use it

By default, Renv uses whatever version of R is installed globally on your system. There are a few ways to use a "frozen" version of R.


If you want to use a specific version of R by default, you can use the Renv global command like this:
Renv global 2.15.2

This will set the default version of R. You can undo this by running: Renv global system


If you want to use a specific version of R for a project, you can use the Renv local command while you're in the project directory:
Renv local 2.15.2

While you are in the project directory, the R version used will be the one you just specified. This overrides the global setting. You can undo this by running: Renv local --unset

Current session

If you want to use a specific version of R only for your current terminal session, you can use the Renv shell command:
Renv shell 2.15.2

After running this command, whenever you use R during the current terminal session, it will be the version you just specified. This overrides both the global and local settings. You can undo this by running: Renv shell --unset

Other helpful commands

  • Renv versions - list what versions of R are installed
  • Renv version - show the currently activated version of R
  • Renv help - get help on Renv commands

Managing packages

Renv does not manage packages, but the devtools package has some functions to help you do this. In particular, the install_version function will let you install a specific version of a CRAN package, even if that package has been pulled from CRAN.

Additionally, you can use the .Rprofile file to set a local library path by calling the .libPaths function. After doing this, R will install and load packages from a directory you specify. This way you can freeze package versions in your project directory.

Additional information

Renv is an altered version of rbenv, which is a tool for managing Ruby versions.


-- JeremyStephens - 12 Nov 2012
Topic attachments
I Attachment Action Size Date Who Comment
increasing-reproducibility.odpodp increasing-reproducibility.odp manage 492.3 K 16 Nov 2012 - 13:21 JeremyStephens Open document presentation
increasing-reproducibility.pdfpdf increasing-reproducibility.pdf manage 430.6 K 16 Nov 2012 - 13:21 JeremyStephens PDF presentation
Topic revision: r4 - 16 Nov 2012, JeremyStephens

This site is powered by FoswikiCopyright © 2013-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Vanderbilt Biostatistics Wiki? Send feedback