A package reference (ref) specifies a location from which an R package
can be obtained from. The full syntax of a reference is
type can be often omitted, the common ref types have shortcuts.
The currently supported reference types are:
cran: a CRAN package.
bioc: A Bioconductor package.
standard: a package from CRAN or Bioconductor.
github: A package from GitHub.
local: A local package file or directory.
url: An URL to a package archive.
installedAn installed package.
depsThe dependencies of a local package file or directory.
anyA special reference type that accepts a package from any source. See below.
If a ref does not explicitly specify a type, then the following rules are applied:
if the ref is a valid
standardref type (without the
if the ref is a valid
githubref type (without the
if the ref is a GitHub URL, then
otherwise an error is thrown.
Package refs may have optional parameters, added after a question mark.
Different parameters are separated by an ampersand (
Parameters might be binary, or have a string value, assigned with an
equal sign (
=). If no value is assigned, then we assume the
value. For example these two package refs are the same:
Some parameters given in a special form allow configuring downstream dependencies:
can be given at the command line and refers to a (potential) downstream package.
Currently supported parameters:
ignoreis a binary parameter. If specified the package is ignored. This usually makes sense in the
packagename=?ignoreform, to ignore a downstream soft dependency. If all versions of a hard dependency are ignored that will lead to a solution error.
ignore-before-ris a version number parameter. The package will be ignored on R versions that are older than the specified one. E.g.
Matrix=?ignore-before-r=4.1.2will ignore the Matrix package on R versions that are older than 4.1.2. This parameter really only makes sense in the
sourceis a binary parameter. If specified, then a source R package is requested from a CRAN-like repository. For package installations
sourcealways triggers a re-install. In other words,
reinstallparameter. This parameter is supported for
standard::remote types, and it is ignore for others.
reinstallrequests a re-install for package installations. It is supported by the
nocachewill ignore the package cache. It will always download the package file, and it will not add the downloaded (and built) file to the package cache. It is supported by the
A package from CRAN. Full syntax:
[cran::]<package>[@[>=]<version> | current | last]
<package>is a valid package name.
<version>is a version or a version requirement.
forecast firstname.lastname@example.org forecast@>=8.8 cran::forecast forecast@last forecast@current
Note: pkgdepends currently parses the version specification part
@), but does not use it.
A package from Bioconductor. The syntax is the same as for CRAN packages, except of the prefix of course:
[bioc::]<package>[@[>=]<version> | current | last]
These are packages either from CRAN or Bioconductor, the full syntax is the same as for CRAN packages, except for the prefix:
[standard::]<package>[@[>=]<version> | current | last]
Packages from a GitHub repository. Full syntax:
<package>is the name of the package. If this is missing, then the name of the repository is used.
<username>is a GitHub username or organization name.
<repository>is the name of the repository.
<subdir>optional subdirectory, if the package is within a subdirectory in the repository.
<detail>specifies a certain version of the package, see below.
<detail> may specify:
a git branch, tag or (prefix of) a commit hash:
a pull request:
the latest release:
<detail> is missing, then the latest commit of the default branch
r-lib/crayon github::r-lib/crayon r-lib/crayon@84be6207 r-lib/crayon@branch r-lib/crayon#41 r-lib/crayon@release
For convenience GitHub HTTP URLs can also be used to specify a package from GitHub. Examples:
https://github.com/r-lib/withr # A branch: https://github.com/r-lib/withr/tree/ghactions # A tag: https://github.com/r-lib/withr/tree/v2.1.1 # A commit: https://github.com/r-lib/withr/commit/8fbcb548e316 # A pull request: https://github.com/r-lib/withr/pull/76 # A release: https://github.com/r-lib/withr/releases/tag/v2.1.0
A GitHub remote string can also be used instead of an URL, for example:
A path that refers to a package file built with
R CMD build, or a
directory that contains a package. Full syntax:
For brevity, you can omit the
local:: prefix, if you specify an
absolute path, a path from the user’s home directory, starting with
or a relative path starting with
A single dot (
".") is considered to be a local package in the current
local::/foo/bar/package_1.0.0.tar.gz local::/foo/bar/pkg local::. /absolute/path/package_1.0.0.tar.gz ~/path/from/home ./relative/path .
You can use
url:: to refer to URLs that hold R package archives
(i.e. properly built with
R CMD build), or compressed directories of
package trees (i.e. not built with
R CMD build). pkgdepends will
figure out if it needs to run
R CMD build on the package first.
This remote type supports
Note that URLs are not ideal remote types, because pkgdepends needs to download the package file to resolve its dependencies. When this happens, it puts the package file in the cache, so no further downloads are needed when installing the package later.
This is usually used internally, but can also be used directly. Full syntax:
<path>is the library the package is installed to.
<package>is the package name.
Usually used internally, it specifies the dependencies of a local package. It can be used to download or install the dependencies of a package, without downloading or installing the package itself. Full syntax:
deps::/foo/bar/package_1.0.0.tar.gz deps::/foo/bar/pkg deps::.
Sometimes you need to install additional packages, but you don’t mind
where they are installed from. Here is an example. You want to install
cli from GitHub, from
r-lib/cli. You also want to install glue, and
you don’t mind which version of glue is installed, as long as it is
compatible with the requested cli version. If cli specifies the
development version of glue, then that is fine. If cli is fine with the
CRAN version of glue, that’s OK, too. If a future version of cli does
not depend on glue, you still want glue installed, from CRAN. The
any:: reference type does exactly this.
In our example you might write
first, but this will fail if
rlib/cli requests (say)
"glue" is interpreted as
"standard::glue", creating a conflict with
tidyverse/glue. On the
works, independently of which glue version is requested by cli.