Install Packages — install • renv

Install one or more R packages, from a variety of remote sources.

Usage

install(
  packages = NULL,
  ...,
  library = NULL,
  type = NULL,
  rebuild = FALSE,
  repos = NULL,
  prompt = interactive(),
  dependencies = NULL,
  project = NULL
)

Arguments

packages: A character vector of R packages to install. Required package dependencies (Depends, Imports, LinkingTo) will be installed as required.
...: Unused arguments, reserved for future expansion. If any arguments are matched to ..., renv will signal an error.
library: The R library to be used. When NULL, the active project library will be used instead.
type: The type of package to install ("source" or "binary"). Defaults to the value of getOption("pkgType").
rebuild: Force packages to be rebuilt, thereby bypassing any installed versions of the package available in the cache? This can either be a boolean (indicating that all installed packages should be rebuilt), or a vector of package names indicating which packages should be rebuilt.
repos: The repositories to use during restore, for packages installed from CRAN or another similar R package repository. When set, this will override any repositories declared in the lockfile. See also the repos.override option in config for an alternate way to provide a repository override.
prompt: Boolean; prompt the user before taking any action? For backwards compatibility, confirm is accepted as an alias for prompt.
dependencies: A vector of DESCRIPTION field names that should be used for package dependency resolution. When NULL (the default), the value of renv::settings$package.dependency.fields is used. The aliases "strong", "most", and "all" are also supported. See tools::package_dependencies() for more details.
project: The project directory. If NULL, then the active project will be used. If no project is currently active, then the current working directory is used instead.

Value

A named list of package records which were installed by renv.

Details

install() uses the same machinery as restore() when installing packages. In particular, this means that the local cache of package installations is used when possible. This helps to avoid re-downloading packages that have already been downloaded before, and re-compiling packages from source when a binary copy of that package is already available.

Project DESCRIPTION Files

If your project contains a DESCRIPTION file, then calling install() without any arguments will instruct renv to install the latest versions of all packages as declared within that DESCRIPTION file's Depends, Imports and LinkingTo fields; similar to how an R package might declare its dependencies.

If you have one or more packages that you'd like to install from a separate remote source, this can be accomplished by adding a Remotes: field to the DESCRIPTION file. See vignette("dependencies", package = "devtools") for more details. Alternatively, view the vignette online at https://devtools.r-lib.org/articles/dependencies.html.

Note that install() does not use the project's renv.lock when determining sources for packages to be installed. If you want to install packages using the sources declared in the lockfile, consider using restore() instead. Otherwise, you can declare the package sources in your DESCRIPTION's Remotes: field.

Remotes Syntax

renv supports a subset of the remotes syntax used for package installation, as described in https://remotes.r-lib.org/articles/dependencies.html. See the examples below for more details.

If you wish to install packages from an external source requiring authentication (e.g. a private GitHub repository), see the Authentication documentation online at https://rstudio.github.io/renv/articles/renv.html#authentication, or view the documentation locally in the Getting Started vignette with vignette("renv", package = "renv").

Bioconductor

Packages from Bioconductor can be installed by using the bioc:: prefix. For example,

renv::install("bioc::Biobase")

will install the latest-available version of Biobase from Bioconductor.

renv depends on BiocManager (or, for older versions of R, BiocInstaller) for the installation of packages from Bioconductor. If these packages are not available, renv will attempt to automatically install them before fulfilling the installation request.

Package Configuration

Many R packages have a configure script that needs to be run to prepare the package for installation. Arguments and environment variables can be passed through to those scripts in a manner similar to install.packages. In particular, the R options configure.args and configure.vars can be used to map package names to their appropriate configuration. For example:

# installation of RNetCDF may require us to set include paths for netcdf
configure.args = c(RNetCDF = "--with-netcdf-include=/usr/include/udunits2"))
options(configure.args = configure.args)
renv::install("RNetCDF")

This could also be specified as, for example,

options(
  configure.args.RNetCDF = "--with-netcdf-include=/usr/include/udunits2"
)
renv::install("RNetCDF")

Similarly, additional flags that should be passed to R CMD INSTALL can be set via the install.opts R option:

# installation of R packages using the Windows Subsystem for Linux
# may require the `--no-lock` flag to be set during install
options(install.opts = "--no-lock")
renv::install("xml2")

# alternatively, you can set such options for specific packages with e.g.
options(install.opts = list(xml2 = "--no-lock"))
renv::install("xml2")

Examples

if (FALSE) {

# install the latest version of 'digest'
renv::install("digest")

# install an old version of 'digest' (using archives)
renv::install("digest@0.6.18")

# install 'digest' from GitHub (latest dev. version)
renv::install("eddelbuettel/digest")

# install a package from GitHub, using specific commit
renv::install("eddelbuettel/digest@df55b00bff33e945246eff2586717452e635032f")

# install a package from Bioconductor
# (note: requires the BiocManager package)
renv::install("bioc::Biobase")

# install a package, specifying path explicitly
renv::install("~/path/to/package")

# install packages as declared in the project DESCRIPTION file
renv::install()

}