Download and install packages from CRAN-like repositories or from local files.
install.packages(pkgs, lib, repos = getOption("repos"),
contriburl = contrib.url(repos, type),
method, available = NULL, destdir = NULL,
dependencies = NA, type = getOption("pkgType"),
configure.args = getOption("configure.args"),
configure.vars = getOption("configure.vars"),
clean = FALSE, Ncpus = getOption("Ncpus", 1L),
verbose = getOption("verbose"),
libs_only = FALSE, INSTALL_opts, quiet = FALSE,
keep_outputs = FALSE, ...)
character vector of the names of packages whose current versions should be downloaded from the repositories.
If this is missing, a listbox of available packages is presented where possible in an interactive R session.
character vector giving the library directories where to
install the packages. Recycled as needed. If missing, defaults to
the first element of
character vector, the base URL(s) of the repositories
to use, e.g., the URL of a CRAN mirror such as
URL(s) of the contrib sections of the repositories. Use this
argument if your repository mirror is incomplete, e.g., because
you mirrored only the ‘contrib’ section, or only have
binary packages. Overrides argument
download method, see
a matrix as returned by
directory where downloaded packages are stored. If it is
logical indicating whether to also install
uninstalled packages which these packages depend on/link
to/import/suggest (and so on recursively).
Not used if
Only supported if
In all of these,
character, indicating the type of package to download and
install. Will be
(Used only for source installs.) A character vector or a named list.
If a character vector with no names is supplied, the elements are
concatenated into a single string (separated by a space) and used as
the value for the --configure-args flag in the call to
A named list can be used also to the same effect, and that allows multi-element character strings for each package which are concatenated to a single string to be used as the value for --configure-args.
(Used only for source installs.) Analogous to
a logical value indicating whether to add the
--clean flag to the call to
the number of parallel processes to use for a parallel
install of more than one source package. Values greater than one
are supported if the
a logical indicating if some “progress report” should be given.
a logical value: should the --libs-only option be used to
install only additional sub-architectures for source installs? (See also
an optional character vector of additional option(s) to be passed to
Can also be a named list of character vectors to be used as additional options, with names the respective package names.
logical: if true, reduce the amount of output. This is not
a logical: if true, keep the outputs from installing source packages in the current working directory, with the names of the output files the package names with ‘.out’ appended. Alternatively, a character string giving the directory in which to save the outputs. Ignored when installing from local files.
This is the main function to install packages. It takes a vector of
names and a destination library, downloads the packages from the
repositories and installs them. (If the library is omitted it
defaults to the first directory in
.libPaths(), with a message
if there is more than one.) If
lib is omitted or is of length
one and is not a (group) writable directory, in interactive use the
code offers to create a personal library tree (the first element of
Sys.getenv("R_LIBS_USER")) and install there.
Detection of a writable directory is problematic on Windows: see the ‘Note’ section.
For installs from a repository an attempt is made to install the
packages in an order that respects their dependencies. This does
assume that all the entries in
lib are on the default library
path for installs (set by environment variable R_LIBS).
You are advised to run
install.packages to ensure that any already installed
dependencies have their latest versions.
This section applies only to platforms where binary packages are available: Windows and CRAN builds for macOS.
R packages are primarily distributed as source packages, but binary packages (a packaging up of the installed package) are also supported, and the type most commonly used on Windows and by the CRAN builds for macOS. This function can install either type, either by downloading a file from a repository or from a local file.
Possible values of
type are (currently)
"win.binary": the appropriate binary type where supported can
also be selected as
For a binary install from a repository, the function checks for the availability of a source package on the same repository, and reports if the source package has a later version, or is available but no binary version is. This check can be suppressed by using
options(install.packages.check.source = "no")
and should be if there is a partial repository containing only binary files.
An alternative (and the current default) is
"both" which means
‘use binary if available and current, otherwise try
source’. The action if there are source packages which are preferred
but may contain code which needs to be compiled is controlled by
type = "both" will be silently changed to
available is specified.
Using packages with
type = "source" always works provided the
package contains no C/C++/Fortran code that needs compilation.
you will need to have installed the Rtools collection as described in the ‘R for Windows FAQ’ and you must have the PATH environment variable set up as required by Rtools.
For a 32/64-bit installation of R on Windows, a small minority of
packages with compiled code need either
INSTALL_opts = "--merge-multiarch" for a
source installation. (It is safe to always set the latter when
installing from a repository or tarballs, although it will be a little
When installing a package on Windows,
install.packages will abort
the install if it detects that the package is already installed and is
currently in use. In some circumstances (e.g., multiple instances of
R running at the same time and sharing a library) it will not detect a
problem, but the installation may fail as Windows locks files in use.
when the package contains C/C++/Fortran code that needs compilation, suitable compilers and related tools need to be installed. On macOS you need to have installed the ‘Command-line tools for Xcode’ (see the ‘R Installation and Administration’ manual) and if needed by the package a Fortran compiler, and have them in your path.
There are various options for locking: these differ between source and binary installs.
By default for a source install, the library directory is
‘locked’ by creating a directory ‘00LOCK’ within it. This
has two purposes: it prevents any other process installing into that
library concurrently, and is used to store any previous version of the
package to restore on error. A finer-grained locking is provided by
the option --pkglock which creates a separate lock for each
package: this allows enough freedom for parallel
installation. Per-package locking is the default when installing a
single package, and for multiple packages when
Ncpus > 1L.
Finally locking (and restoration on error) can be suppressed by
For a macOS binary install, no locking is done by default. Setting
TRUE (it defaults to the value of
getOption("install.lock", FALSE)) will use per-directory
locking as described for source installs. For Windows binary install,
per-directory locking is used by default (
lock defaults to the
getOption("install.lock", TRUE)). If the value is
"pkglock" per-package locking will be used.
If package locking is used on Windows with
libs_only = TRUE and
the installation fails, the package will be restored to its previous
Note that it is possible for the package installation to fail so badly
that the lock directory is not removed: this inhibits any further
installs to the library directory (or for
--pkglock, of the
package) until the lock directory is removed manually.
Parallel installs are attempted if
pkgs has length greater than
Ncpus > 1. It makes use of a parallel
make specified (default
make) when R was
built must be capable of supporting
make -j n: GNU make,
pmake do, but Solaris
make do not: if necessary environment variable
MAKE can be set for the current session to select a suitable
install.packages needs to be able to compute all the
available, including if one
pkgs depends indirectly on another. This means that
if for example you are installing CRAN packages which depend
on Bioconductor packages which in turn depend on CRAN
available needs to cover both CRAN and
A limit on the elapsed time for each call to
R CMD INSTALL
(so for source installs) can be set via environment variable
_R_INSTALL_PACKAGES_ELAPSED_TIMEOUT_: in seconds (or in minutes
or hours with optional suffix ‘m’ or ‘h’, suffix ‘s’
being allowed for the default seconds) with
0 meaning no limit.
For non-parallel installs this is implemented via the
timeout argument of
system2: for parallel
installs via the OS's
timeout command. (The one
tested is from GNU coreutils, commonly available on Linux but
not other Unix-alikes. If no such command is available the timeout
request is ignored, with a warning. On Windows, one needs to specify
timeout command via environment variable
R_TIMEOUT, because ‘c:/Windows/system32/timeout.exe’ is
not.) For parallel installs a
‘Error 124’ message from
make indicates that timeout
Timeouts during installation might leave lock directories behind and not restore previous versions.
If you are not running an up-to-date version of R you may see a message like
package 'RODBC' is not available (for R version 3.5.3)
One possibility is that the package is not available in any of the
selected repositories; another is that is available but only for
current or recent versions of R. For CRAN packages take
a look at the package's CRAN page (e.g.,
https://cran.r-project.org/package=RODBC). If that indicates in
the ‘Depends’ field a dependence on a later version of R you
will need to look in the ‘Old sources’ section and select the URL
of a version of comparable age to your R. Then you can supply that
URL as the first argument of
install.packages(): you may
need to first manually install its dependencies.
For other repositories, using
"OS_type")[pkgname, ] will show if the package is available
for any R version (for your OS).
Some binary distributions of R have
INSTALL in a separate
bundle, e.g. an
give an error if called with
type = "source" on such a system.
Some binary Linux distributions of R can be installed on a machine without the tools needed to install packages: a possible remedy is to do a complete install of R which should bring in all those tools as dependencies.
install.packages tries to detect if you have write permission
on the library directories specified, but Windows reports unreliably.
If there is only one library directory (the default), R tries to
find out by creating a test directory, but even this need not be the
whole story: you may have permission to write in a library directory
but lack permission to write binary files (such as ‘.dll’ files)
there. See the ‘R for Windows FAQ’ for workarounds.
download.file for how to handle proxies and
other options to monitor file transfers.
untar for manually unpacking source package tarballs.
The ‘R Installation and Administration’ manual for how to set up a repository.
## Not run:
## A Linux example for Fedora's layout of udunits2 headers.
configure.args = c(RNetCDF = "--with-netcdf-include=/usr/include/udunits2"))
## End(Not run)