| install.packages | R Documentation |
Description
Download and install packages from CRAN-like repositories or fromlocal files.
Usage
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, ...)Arguments
pkgs | character vector of the names of packages whosecurrent versions should be downloaded from the repositories. If
If this is missing, a listbox ofavailable packages is presented where possible in an interactive Rsession. |
lib | character vector giving the library directories where toinstall the packages. Recycled as needed. If missing, defaults tothe first element of |
repos | character vector, the base URL(s) of the repositoriesto use, e.g., the URL of a CRAN mirror such as Can be |
contriburl | URL(s) of the contrib sections of the repositories. Use thisargument if your repository mirror is incomplete, e.g., becauseyou burned only the ‘contrib’ section on a CD, or only havebinary packages. Overrides argument |
method | download method, see |
available | a matrix as returned by |
destdir | directory where downloaded packages are stored. If it is |
dependencies | logical indicating whether to also installuninstalled packages which these packages depend on/linkto/import/suggest (and so on recursively).Not used if Only supported if The default,
In all of these, |
type | character, indicating the type of package to download andinstall. Will be |
configure.args | (Used only for source installs.) A character vector or a named list.If a character vector with no names is supplied, the elements areconcatenated into a single string (separated by a space) and used asthe value for the --configure-args flag in the call to A named list can be used also to the same effect, and thatallows multi-element character strings for each packagewhich are concatenated to a single string to be used as thevalue for --configure-args. |
configure.vars | (Used only for source installs.) Analogous to |
clean | a logical value indicating whether to add the--clean flag to the call to |
Ncpus | the number of parallel processes to use for a parallelinstall of more than one source package. Values greater than oneare supported if the |
verbose | a logical indicating if some “progress report” should be given. |
libs_only | a logical value: should the --libs-only option be used toinstall only additional sub-architectures for source installs? (See also |
INSTALL_opts | an optional character vector of additional option(s) to be passed to Can also be a named list of character vectors to be used asadditional options, with names the respective package names. |
quiet | logical: if true, reduce the amount of output. This is notpassed to |
keep_outputs | a logical: if true, keep the outputs from installing source packagesin the current working directory, with the names of the output filesthe package names with ‘.out’ appended. Alternatively, acharacter string giving the directory in which to save the outputs.Ignored when installing from local files. |
... | Arguments to be passed to |
Details
This is the main function to install packages. It takes a vector ofnames and a destination library, downloads the packages from therepositories and installs them. (If the library is omitted itdefaults to the first directory in .libPaths(), with a messageif there is more than one.) If lib is omitted or is of lengthone and is not a (group) writable directory, in interactive use thecode offers to create a personal library tree (the first element ofSys.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 thepackages in an order that respects their dependencies. This doesassume that all the entries in lib are on the default librarypath for installs (set by environment variable R_LIBS).
You are advised to run update.packages beforeinstall.packages to ensure that any already installeddependencies have their latest versions.
Value
Invisible NULL.
Binary packages
This section applies only to platforms where binary packages areavailable: Windows and CRAN builds for macOS.
R packages are primarily distributed as source packages, butbinary packages (a packaging up of the installed package) arealso supported, and the type most commonly used on Windows and by theCRAN builds for macOS. This function can install either type, either bydownloading a file from a repository or from a local file.
Possible values of type are (currently) "source","mac.binary", and"win.binary": the appropriate binary type where supported canalso be selected as "binary".
For a binary install from a repository, the function checks for theavailability of a source package on the same repository, and reportsif the source package has a later version, or is available but nobinary 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 binaryfiles.
An alternative (and the current default) is "both" which means‘use binary if available and current, otherwise trysource’. The action if there are source packages which are preferredbut may contain code which needs to be compiled is controlled bygetOption("install.packages.compile.from.source").type = "both" will be silently changed to "binary" ifeither contriburl or available is specified.
Using packages with type = "source" always works provided thepackage contains no C/C++/Fortran code that needs compilation.Otherwise,
- on Windows
you will need to have installed the Rtoolscollection as described in the ‘R for Windows FAQ’ andyou must have the PATH environment variable set up as requiredby Rtools.
For a 32/64-bit installation of R on Windows, a small minority ofpackages with compiled code need either
INSTALL_opts = "--force-biarch"orINSTALL_opts = "--merge-multiarch"for asource installation. (It is safe to always set the latter wheninstalling from a repository or tarballs, although it will be a littleslower.)When installing a package on Windows,
install.packageswill abortthe install if it detects that the package is already installed and iscurrently in use. In some circ*mstances (e.g., multiple instances ofR running at the same time and sharing a library) it will not detect aproblem, but the installation may fail as Windows locks files in use.- On Unix-alikes,
when the package contains C/C++/Fortran codethat needs compilation, on macOS you need to have installed the‘Command-line tools for Xcode’ (see the‘R Installation and Administration’ manual) and if neededby the package a Fortran compiler, and have them in your path.
Locking
There are various options for locking: these differ between source andbinary installs.
By default for a source install, the library directory is‘locked’ by creating a directory ‘00LOCK’ within it. Thishas two purposes: it prevents any other process installing into thatlibrary concurrently, and is used to store any previous version of thepackage to restore on error. A finer-grained locking is provided bythe option --pkglock which creates a separate lock for eachpackage: this allows enough freedom for parallelinstallation. Per-package locking is the default when installing asingle package, and for multiple packages when Ncpus > 1L.Finally locking (and restoration on error) can be suppressed by--no-lock.
For a macOS binary install, no locking is done by default. Settingargument lock to TRUE (it defaults to the value ofgetOption("install.lock", FALSE)) will use per-directorylocking as described for source installs. For Windows binary install,per-directory locking is used by default (lock defaults to thevalue of 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 andthe installation fails, the package will be restored to its previousstate.
Note that it is possible for the package installation to fail so badlythat the lock directory is not removed: this inhibits any furtherinstalls to the library directory (or for --pkglock, of thepackage) until the lock directory is removed manually.
Parallel installs
Parallel installs are attempted if pkgs has length greater thanone and Ncpus > 1. It makes use of a parallel make,so the make specified (default make) when R wasbuilt must be capable of supporting make -j n: GNU make,dmake and pmake do, but Solaris make andolder FreeBSD make do not: if necessary environment variableMAKE can be set for the current session to select a suitablemake.
install.packages needs to be able to compute all thedependencies of pkgs from available, including if oneelement of pkgs depends indirectly on another. This means thatif for example you are installing CRAN packages which dependon Bioconductor packages which in turn depend on CRANpackages, available needs to cover both CRAN andBioconductor packages.
Timeouts
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 minutesor hours with optional suffix m or h, suffix sbeing allowed for the default seconds) with 0 meaning no limit.
For non-parallel installs this is implemented via thetimeout argument of system2: for parallelinstalls via the OS's timeout command. (The onetested is from GNU coreutils, commonly available on Linux butnot other Unix-alikes. If no such command is available the timeoutrequest is ignored, with a warning.) For parallel installs aError 124 message from make indicates that timeoutoccurred.
Timeouts during installation might leave lock directories behind andnot restore previous versions.
Version requirements on source installs
If you are not running an up-to-date version of R you may see amessage like
package 'RODBC' is not available (for R version 3.5.3)
One possibility is that the package is not available in any of theselected repositories; another is that is available but only forcurrent or recent versions of R. For CRAN packages takea look at the package's CRAN page (e.g.,https://cran.r-project.org/package=RODBC). If that indicates inthe Depends field a dependence on a later version of R youwill need to look in the Old sources section and select the URLof a version of comparable age to your R. Then you can supply thatURL as the first argument of install.packages(): you mayneed to first manually install its dependencies.
For other repositories, using available.packages(filters = "OS_type")[pkgname, ] will show if the package is availablefor any R version (for your OS).
Note
- On Unix-alikes:
Some binary distributions of R have
INSTALLin a separatebundle, e.g. anR-develRPM.install.packageswillgive an error if called withtype = "source"on such a system.Some binary Linux distributions of R can be installed on a machinewithout the tools needed to install packages: a possible remedy is todo a complete install of R which should bring in all those tools asdependencies.
- On Windows:
install.packagestries to detect if you have write permissionon the library directories specified, but Windows reports unreliably.If there is only one library directory (the default), R tries tofind out by creating a test directory, but even this need not be thewhole story: you may have permission to write in a library directorybut lack permission to write binary files (such as ‘.dll’ files)there. See the ‘R for Windows FAQ’ for workarounds.
See Also
update.packages,available.packages,download.packages,installed.packages,contrib.url.
See download.file for how to handle proxies andother options to monitor file transfers.
untar for manually unpacking source package tarballs.
INSTALL, REMOVE, remove.packages,library, .packages, read.dcf
The ‘R Installation and Administration’ manual for how toset up a repository.
Examples
## Not run: ## A Linux example for Fedora's layout of udunits2 headers.install.packages(c("ncdf4", "RNetCDF"), configure.args = c(RNetCDF = "--with-netcdf-include=/usr/include/udunits2"))## End(Not run)