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 forprompt
.- dependencies
A vector of DESCRIPTION field names that should be used for package dependency resolution. When
NULL
(the default), the value ofrenv::settings$package.dependency.fields
is used. The aliases "strong", "most", and "all" are also supported. Seetools::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.
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,
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()
}