install.packages {utils} | R Documentation

## Install Packages from Repositories or Local Files

### Description

Download and install packages from CRAN-like repositories or from local 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),
                     libs_only = FALSE, INSTALL_opts, ...)

### Arguments

`pkgs`

character vector of the names of packages whose current versions should be downloaded from the repositories.

If `repos = NULL`, a character vector of file paths of ‘.tar.gz’ files. These can be source archives or binary package archive files (as created by `R CMD build --binary`). On a CRAN build of R for Mac OS X these can be ‘.tgz’ files containing binary package archives. Tilde-expansion will be done on the file paths.

If this is missing or a zero-length character vector, a listbox of available packages is presented where possible in an interactive R session.

`lib` | character vector giving the library directories where to install the packages. Recycled as needed. If missing, defaults to the first element of `.libPaths()`.
`repos` | character vector, the base URLs of the repositories to use, e.g., the URL of a CRAN mirror such as `"http://cran.us.r-project.org"`. Can be `NULL` to install from local files (with extension ‘.tar.gz’ for source packages).
`contriburl` | URL(s) of the contrib sections of the repositories. Use this argument only if your repository mirror is incomplete, e.g., because you burned only the ‘contrib’ section on a CD. Overrides argument `repos`. As with `repos`, can also be `NULL` to install from local files.
`method` | download method, see `download.file`.
`available` | an object as returned by `available.packages` listing packages available at the repositories, or `NULL` when the function makes an internal call to `available.packages`.
`destdir` | directory where downloaded packages are stored. If it is `NULL` (the default) a subdirectory `downloaded_packages` of the session temporary directory will be used (and the files will be deleted at the end of the session).

`dependencies`

logical indicating to also install uninstalled packages which these packages depend on/link to/import/suggest (and so on recursively). Not used if `repos = NULL`. Can also be a character vector, a subset of `c("Depends", "Imports", "LinkingTo", "Suggests", "Enhances")`.

Only supported if `lib` is of length one (or missing), so it is unambiguous where to install the dependent packages. If this is not the case it is ignored, with a warning.

The default, `NA`, means `c("Depends", "Imports", "LinkingTo")`.

`TRUE` means (as from R 2.15.0) to use `c("Depends", "Imports", "LinkingTo", "Suggests")` for `pkgs` and `c("Depends", "Imports", "LinkingTo")` for added dependencies: this installs all the packages needed to run `pkgs`, their examples, tests and vignettes (if the package author specified them correctly).

`type`

character, indicating the type of package to download and install.

Possible values are `"source"`, `"mac.binary.leopard"` and `"win.binary"`: the binary types can be listed and downloaded but not installed on other platforms.

The default is the appropriate binary type on Windows and on the CRAN binary Mac OS X distribution, otherwise `"source"`. For the platforms where binary packages are the default, an alternative is `"both"` which means ‘try binary if available, otherwise try source’. (This will only choose the binary package if its version number is no older than the source version.)

`configure.args`

(not used on Windows) 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 `R CMD INSTALL`. If the character vector has names these are assumed to identify values for --configure-args for individual packages. This allows one to specify settings for an entire collection of packages which will be used if any of those packages are to be installed. (These settings can therefore be re-used and act as default settings.)

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.

`configure.vars` | (not used on Windows) analogous to `configure.args` for flag --configure-vars, which is used to set environment variables for the `configure` run.
`clean` | a logical value indicating whether to specify to add the --clean flag to the call to `R CMD INSTALL`. This is sometimes used to perform additional operations at the end of the package installation in addition to removing intermediate files.
`Ncpus` | 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 `make` command specified by `Sys.getenv("MAKE", "make")` accepts argument `-k -j Ncpus`.
`libs_only` | a logical value: should the --libs-only option be used to install only additional sub-architectures? (See also `INSTALL_opts`.) This can also be used on Windows to install just the DLL(s) from a binary package, e.g. to add 64-bit DLLs to a 32-bit install.
`INSTALL_opts` | an optional character vector of additional option(s) to be passed to `R CMD INSTALL` for a source package install. E.g. `c("--html", "--no-multiarch")`.
`...` | Arguments to be passed to `download.file` (e.g. `quiet = TRUE`), or to the functions for binary installs on Mac OS X and Windows (which accept an argument `"lock"`: see the section on ‘Locking’).

### Details

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 from the CRAN distribution for Mac OS X. This function can install either type where supported, either by downloading a file from a repository or from a local file. The default type is given by `getOption("pkgType")`: this defaults to `"source"` apart from under Windows or a CRAN binary distribution for Mac OS X.

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, the code offers to create a personal library tree (the first element of `Sys.getenv("R_LIBS_USER")`) and install there.

For source packages 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 R_LIBS).

You are advised to run `update.packages` before `install.packages` to ensure that any already installed dependencies have their latest versions.

Argument `libs_only = TRUE` is supported for source installs and for Windows binary installs.

### Value

Invisible `NULL`.

### Locking

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 --no-lock.

For a Mac OS X or Windows binary install, no locking is done by default. Setting argument `lock` to `TRUE` (it defaults to the value of `getOption("install.lock", FALSE)`) will use per-directory locking as described for source installs: 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 state.

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

Parallel installs are attempted if `pkgs` has length greater than one and `Ncpus > 1`. It makes use of a parallel `make`, so the `make` specified (default `make`) when R was built must be capable of supporting `make -j n`: GNU make and `dmake` do, but FreeBSD and Solaris `make` do not: if necessary environment variable MAKE can be set for the current session to select a suitable `make`.

`install.packages` needs to be able to compute all the dependencies of `pkgs` from `available`, including if one element of `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 packages, `available` needs to cover both CRAN and Bioconductor packages.

### Note

Some binary distributions of R have `INSTALL` in a separate bundle, e.g. an `R-devel` RPM. `install.packages` will give an error if called with `type = "source"` on such a system.

Some binary distributions of R can be installed on a machine without the tools needed to install packages: the remedy is to do a complete install of R which should bring in all those tools as dependencies.

### See Also

`update.packages`, `available.packages`, `download.packages`, `installed.packages`, `contrib.url`.

See `download.file` for how to handle proxies and other options to monitor file transfers.

`INSTALL`, `REMOVE`, `remove.packages`, `library`, `.packages`, `read.dcf`

The ‘R Installation and Administration’ manual for how to set up a repository.

### Examples

    ## Not run:
    install.packages(
        c("XML_0.99-5.tar.gz",
          "../../Interfaces/Perl/RSPerl_0.8-0.tar.gz"),
        repos = NULL,
        configure.args = c(XML = '--with-xml-config=xml-config',
                           RSPerl = "--with-modules='IO Fcntl'"))

    ## End(Not run)

[Package utils version 2.15.1 Index]