Install Add-on Packages
Utility for installing add-on packages.
R CMD INSTALL [options] [-l lib] pkgs
a space-separated list with the path names of the packages to be installed. See ‘Details’.
the path name of the R library tree to install to. Also accepted in the form ‘--library=lib’. Paths including spaces should be quoted, using the conventions for the shell in use.
a space-separated list of options through which in
particular the process for building the help files can be controlled.
This will stop at the first error, so if you want all the
to be tried, call this via a shell loop.
If used as
R CMD INSTALL pkgs without explicitly specifying
lib, packages are installed into the library tree rooted at the
first directory in the library path which would be used by R run in
the current environment.
To install into the library tree
R CMD INSTALL -l lib pkgs.
lib to the library path for
duration of the install, so required packages in the installation
directory will be found (and used in preference to those in other
lib and the elements of
pkgs may be absolute or
relative path names of directories.
pkgs may also contain
names of package archive files: these are then extracted to a
temporary directory. These are tarballs containing a single
directory, optionally compressed by
Finally, binary package archive files (as created by
R CMD INSTALL --build) can be supplied.
Tarballs are by default unpackaged by the internal
function: if needed an external
tar command can be specified
by the environment variable R_INSTALL_TAR: please ensure that it
can handle the type of compression used on the tarball. (This is
sometimes needed for tarballs containing invalid or unsupported
sections, and can be faster on very large tarballs. Setting
R_INSTALL_TAR to ‘tar.exe’ has been needed to overcome
permissions issues on some Windows systems.)
The package sources can be cleaned up prior to installation by --preclean or after by --clean: cleaning is essential if the sources are to be used with more than one architecture or platform.
Some package sources contain a ‘configure’ script that can be
passed arguments or variables via the option --configure-args
and --configure-vars, respectively, if necessary. The latter
is useful in particular if libraries or header files needed for the
package are in non-system directories. In this case, one can use the
CPPFLAGS to specify these
locations (and set these via --configure-vars), see section
‘Configuration variables’ in
‘R Installation and Administration’ for more information.
(If these are used more than
once on the command line they are concatenated.) The configure
mechanism can be bypassed using the option --no-configure.
If the attempt to install the package fails, leftovers are removed. If the package was already installed, the old version is restored. This happens either if a command encounters an error or if the install is interrupted from the keyboard: after cleaning up the script terminates.
For details of the locking which is done, see the section
‘Locking’ in the help for
Option --build can be used to tar up the installed package
for distribution as a binary package (as used on macOS). This is done
utils::tar unless environment variable R_INSTALL_TAR
By default a package is installed with static HTML help pages if and only if R was: use options --html and --no-html to override this.
Packages are not by default installed keeping the source formatting
keep.source argument to
can be enabled by the option --with-keep.source or by setting
environment variable R_KEEP_PKG_SOURCE to
Specifying the --install-tests option copies the contents of the ‘tests’ directory into the package installation. If the R_ALWAYS_INSTALL_TESTS environment variable is set to a true value, the tests will be installed even if --install-tests is omitted.
R CMD INSTALL --help for concise usage information,
including all the available options.
An R installation can support more than one sub-architecture: currently this is most commonly used for 32- and 64-bit builds on Windows.
For such installations, the default behaviour is to try to install
source packages for all installed sub-architectures unless the package
has a configure script or a ‘src/Makefile’ (or
‘src/Makefile.win’ on Windows), when only compiled code for the
R CMD INSTALL is installed.
To install a source package with compiled code only for the
sub-architecture used by
R CMD INSTALL, use
--no-multiarch. To install just the compiled code for
another sub-architecture, use --libs-only.
There are two ways to install for all available sub-architectures. If
the configure script is known to work for both Windows architectures,
use flag --force-biarch (and packages can specify this
via a ‘Biarch: yes’ field in their
Second, a single tarball can be installed with
R CMD INSTALL --merge-multiarch mypkg_version.tar.gz
The default way to install source packages changed in R 3.6.0, so packages are first installed to a temporary location and then (if successful) moved to the destination library directory. Some older packages were written in ways that assume direct installation to the destination library.
Staged installation can currently be overridden by having a line ‘StagedInstall: no’ in the package's ‘DESCRIPTION’ file, via flag --no-staged-install or by setting environment variable R_INSTALL_STAGED to a false value (e.g. ‘false’ or ‘no’).
Staged installation requires either --pkglock or --lock, one of which is used by default.
The options do not have to precede ‘pkgs’ on the command line, although it will be more legible if they do. All the options are processed before any packages, and where options have conflicting effects the last one will win.
Some parts of the operation of
INSTALL depend on the R
temporary directory (see
tempdir, usually under
‘/tmp’) having both write and execution access to the account
running R. This is usually the case, but if ‘/tmp’ has been
noexec, environment variable TMPDIR may need
to be set to a directory from which execution is allowed.
.libPaths for information on using several library trees;
install.packages for R-level installation of packages;
update.packages for automatic update of packages using
the Internet or a local repository.
The chapter on ‘Add-on packages’ in
‘R Installation and Administration’
and the chapter on ‘Creating R packages’ in
‘Writing R Extensions’
RShowDoc or in the ‘doc/manual’
subdirectory of the R source tree.