rig pkg

Look up R packages, in the package repositories rig configures for your R installations and in the libraries they are installed into, and install them, mostly without starting R.

rig pkg available lists every package the repositories offer, rig pkg info shows the DESCRIPTION of one package, or, with --versions, all of its versions, rig pkg deps lists the packages one package needs, directly or, with --recursive, transitively, and rig pkg tree shows those transitive dependencies as a tree instead of a table.

rig pkg install, rig pkg list and rig pkg remove are the subcommands that work on a package library instead of the repositories: they install packages and their dependencies into it, list the packages that are actually installed, and delete some of them.

The repositories themselves are managed by rig repos, the libraries by rig library.

Subcommands

available: List packages available in the R package repositories
deps: Dependencies of a package in the repositories
info: Information about a package in the repositories
install: Install packages from the repositories
list: Packages installed in a library (alias: ls)
remove: Remove packages from a library (alias: rm)
tree: Dependency tree of a package in the repositories

`rig pkg available`

Note

This command currently only uses P3M (Posit Public Package Manager) and ignores the configured repositories.

List the packages available from P3M’s full package history ordered by name, using the latest version of each package. For each package rig shows its version and its number of hard dependencies (Depends, Imports and LinkingTo, excluding R and the base packages).

Packages CRAN has archived are omitted by default; pass --include-archived to list them as well.

Use --json to print the full listing as JSON, including the complete dependency lists for every package. See rig pkg info for a detailed view of a single package, and rig pkg info --versions to list all versions of a package.

Usage

rig pkg available [OPTIONS]

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
-h, --help: Print help (see a summary with ‘-h’)
--include-archived: Also list packages CRAN has archived
--json: JSON output
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user: Run in user mode (overrides RIG_MODE and config)

`rig pkg deps`

Note

This command currently only uses P3M (Posit Public Package Manager) and ignores the configured repositories.

Show what a package needs, in a table: every package it depends on, the version of that package currently on CRAN, the dependency type (Depends, Imports, LinkingTo) and the version requirement, if it has one.

By default the dependencies of the latest version of the package are shown; use --version to ask about a specific one, including versions that CRAN has archived. Use --json for machine readable output.

Dependency types

By default rig lists the hard dependencies only: Depends, Imports and LinkingTo, i.e. the packages that need to be installed to use the package. --dev adds the soft dependencies, Suggests and Enhances, which are typically only needed to run the tests, build the vignettes or use some optional feature.

R itself and the base packages are listed if the package depends on them, with their version requirement, but without a version of their own, as they are part of R.

--recursive (-r) shows the whole dependency closure. Each package appears once, with the Depth column giving its distance from the queried package, and the Needed by column naming the packages that pull it in.

See rig pkg tree for a visual dependency tree.

rig follows the dependencies of the latest version of every package in the tree, so a version requirement that would force an older version, with different dependencies, is not taken into account. Use rig proj lock for a resolution that is consistent across versions.

Usage

rig pkg deps [OPTIONS] <package>

Arguments

<package>: package to show the dependencies of

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--dev: Include dev (development) dependencies
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --recursive: Show recursive (transitive) dependencies
--user: Run in user mode (overrides RIG_MODE and config)
-v, --version <version>: package version to use (default: latest)

`rig pkg info`

Show information about a package on CRAN, from its DESCRIPTION file.

By default the latest available version is shown; use --version to select a specific one, including versions that CRAN has archived. Use --json to print all DESCRIPTION fields.

If CRAN has archived the package, i.e. removed it from the current repository, rig shows the date it was archived, next to the publication date of the version. --json reports it as an extra Archived field.

README of a package

--readme prints the README of the package, instead of its metadata, exactly as the repository stores it, i.e. not rendered and not paged. It works together with --version, to get the README of an older version, but not with --versions.

--readme --json prints an object with the package and version the README belongs to, the readme itself, and the format it is written in. The format is the one the repository reports, e.g. md for markdown or txt for plain text.

A package without a README is not an error. --readme then prints nothing, and --readme --json prints null for both readme and format.

All versions of a package

--versions lists all versions of the package ever published on CRAN, oldest first, instead of the details of a single version. For each version rig shows its publication date, its R version requirement and its number of hard dependencies (Depends, Imports and LinkingTo, excluding R and the base packages); the latest version is marked. It cannot be combined with --version.

For a package CRAN has archived, i.e. removed from the current repository, the header also shows the date it was archived. This applies to the package as a whole, so all of its versions are archived.

--versions --json prints the full DESCRIPTION of every version, each with an extra Archived field for an archived package.

Usage

rig pkg info [OPTIONS] <package>

Arguments

<package>: package to show

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--readme: Show the README of the package, instead of its metadata
--user: Run in user mode (overrides RIG_MODE and config)
-v, --version <version>: package version to show (default: latest)
--versions: List all versions of the package, instead of the details of one

`rig pkg install`

Install one or more R packages, and everything they need, into an R package library.

rig pkg install cli glue

✓ Solved dependencies
2 of 2 packages to install (R 4.4.1, main: /Users/gaborcsardi/Library/R/arm64/4.4/library)
Package  Version  Type    Action   Reason
cli      3.6.3    binary  install  not installed
glue     1.8.0    binary  install  not installed
✓ Installed 2 packages (R 4.4.1, main: /Users/gaborcsardi/Library/R/arm64/4.4/library)

rig resolves the whole dependency tree first, the same way rig proj lock does for a project, so a package is only installed if every package it needs can be installed with it, at versions that work together. --dry-run runs the resolution and reports what it would install, without installing anything.

Package names are case sensitive, as they are in R. Naming the same package twice is not an error, it is installed once.

Dev dependencies

By default rig installs the hard dependencies only: Depends, Imports and LinkingTo, i.e. the packages that need to be installed to use the package. --dev also installs the soft dependencies, Suggests and Enhances, which are typically only needed to run the tests, build the vignettes or use some optional feature.

--dev applies to the packages named on the command line only. A dev dependency is installed with everything it needs to be installed, but not with its own dev dependencies, so --dev does not grow without bounds.

A package often suggests packages that are not in the repositories rig installs from, e.g. Bioconductor packages. Those cannot be installed, and by default rig reports them and installs nothing. --ignore-unavailable installs the rest of the dev dependencies instead, and names the ones it skipped. It only applies to dev dependencies: a hard dependency that is not available is always an error, and so is a dev dependency that exists but has no version that fits.

Binary and source packages

A binary package is a package that has already been built for your platform and R version. Installing one is unpacking it into the library, so rig does that itself and never starts R.

A package with no binary build is installed from its source tarball, with R CMD INSTALL, which does start R, and needs whatever that package needs to compile. The output of the compilation goes into a log file per package, in a _logs directory inside the library, and rig points at the log when an installation fails.

--platform installs for a platform other than this machine’s, and --platform source installs source packages only. --prefer-binary trades a newer version for an older one that has a binary build, which is useful when compiling is expensive; it takes the number of versions to look back through, e.g. --prefer-binary=5, and defaults to 3.

Packages rig builds itself

Compiling a package produces exactly what a repository would have served as a binary package, so rig keeps it: a source install is archived into the cache, with the same file name R CMD INSTALL --build would have given it, and installing that package again unpacks the archive instead of compiling it a second time. That covers another library, another project, and --reinstall, which reinstalls a package but does not recompile it.

A cache entry belongs to one platform, one R minor version, one source tarball, one set of versions of the packages it is compiled against, and one set of ~/.R/Makevars files. Change any of those and the package is compiled again. What it does not cover is your compiler, the system libraries the package found when it was configured, and the arguments it was configured with; a machine whose toolchain changed under it can hold an entry that no longer matches, and the way out is to delete it. rig system dirs --cache says where the cache is.

--no-cache turns all of this off for one run: rig then downloads the repository metadata and the package files again, compiles every source package rather than unpacking one it built earlier, and adds nothing to the cache. See rig config.

What gets skipped

rig does not install a package that is already installed and up to date, so running the same command twice does nothing the second time.

Being up to date is more than having the right version number. A repository can publish several builds of one version, and a package with compiled code only works with the versions of the packages it was compiled against — an R that loads a package built against a different one can crash rather than complain. So rig keeps track of which build each package it installs came from, and what that build was compiled against, and reinstalls a package whose build is no longer the one the resolution picked.

That check cascades: replacing a package also replaces the packages that were compiled against it, and the packages compiled against those.

rig only knows this about packages it installed itself, so a package that R, pak or renv installed is always reinstalled rather than assumed to match. --reinstall installs everything in the resolution regardless.

Which library

By default rig installs into the default library of the default R version, i.e. the library that rig library default reports, and the one R installs packages into.

--library (-l) selects another library. It takes either the name of a library of the R version, as rig library list prints them, or the path of a library directory:

rig pkg install --library myproject cli
rig pkg install --library /usr/lib/R/site-library cli

A path is used as it is, and is created if it does not exist yet, so it does not need to belong to an R version rig manages.

--r-version (-r) selects the library of another R version, instead of the default one, as it does for the rig library commands. It has no effect on which library --library names when that is a path, but it still decides which binary packages fit, and which R installs a source package.

In admin mode the site and system libraries of an R installation belong to the administrator, so installing into them needs sudo (an administrator account on Windows). Your own user library never does.

Usage

rig pkg install [OPTIONS] <package>...

Arguments

<package>...: packages to install

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--dev: Include dev (development) dependencies
--dry-run: Show what would be installed, install nothing
-h, --help: Print help (see a summary with ‘-h’)
--ignore-unavailable: Skip dev dependencies that are not available in the repositories, instead of failing
--json: JSON output
-l, --library <library>: Library name or path, instead of the default library
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--platform <platform>: Platform to install binary packages for, e.g. macos, windows, ubuntu-24.04, or a full platform string like aarch64-unknown-linux-gnu-ubuntu-24.04 (default: this machine). Use --platform source to install source packages only.
--prefer-binary[=<prefer-binary>]: Prefer an older version that has a binary package over a newer one that does not. Optionally give how many of the newest versions to consider, e.g. --prefer-binary=5 (default: 3).
-r, --r-version <r-version>: R version to operate on, instead of the default
--reinstall: Install the packages even if they are already up to date
--user: Run in user mode (overrides RIG_MODE and config)

`rig pkg list`

Alias: rig pkg ls

List the packages installed in an R package library, without starting R.

312 packages (R 4.4.1, main: /Users/gaborcsardi/Library/R/arm64/4.4/library)

Package     Version      Built   Platform                 Source
-----------------------------------------------------------------------------
cli         3.6.3        4.4.0   aarch64-apple-darwin20   CRAN
glue        1.8.0        4.4.1   aarch64-apple-darwin20   CRAN
asciicast   2.3.1.9000   4.4.1   aarch64-apple-darwin20   github::r-lib/asciicast
mypkg       0.0.1        4.4.1   -                        -

The first line names the number of packages and the library they were found in. Each line below it names a package, its version, the R version it was built for, the platform it was built for, and where it was installed from.

Platform is empty for a package installed from source. Source is the repository the package came from, e.g. CRAN, and for a package installed from somewhere else it names that place instead, in the package reference syntax pak uses: github::<user>/<repo> for a GitHub install, git::<url> for a git one, and so on. It is empty for a package installed from a local directory, as R CMD INSTALL and devtools::install() do, because such a package records nothing about where its source was.

A field the package’s DESCRIPTION does not have is shown as -. Use --json for machine readable output, which reports the repository or remote type as source and the remote itself as remote, separately.

This subcommand and rig pkg remove read an installed library; the others, e.g. rig pkg available, read the package repositories that packages are installed from.

Which library

By default rig lists the default library of the default R version, i.e. the library that rig library default reports, and the one R installs packages into.

--library (-l) selects another library. It takes either the name of a library of the R version, as rig library list prints them, or the path of a library directory:

rig pkg list --library myproject
rig pkg list --library /usr/lib/R/site-library

A path is used as it is, so it does not need to belong to an R version rig manages, and rig does not need an R version at all to list it.

--r-version (-r) lists the library of another R version, instead of the default one, as it does for the rig library commands. It has no effect when --library is a path.

Subdirectories that are not packages are left out: rig’s own libraries of a main library, and the leftovers of an interrupted installation.

Usage

rig pkg list [OPTIONS]

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
-l, --library <library>: Library name or path, instead of the default library
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: R version to operate on, instead of the default
--user: Run in user mode (overrides RIG_MODE and config)

`rig pkg remove`

Alias: rig pkg rm

Delete one or more installed packages from an R package library, without starting R.

rig pkg remove cli glue

▶ Removing cli 3.6.3 from /Users/gaborcsardi/Library/R/arm64/4.4/library/cli...
▶ Removing glue 1.8.0 from /Users/gaborcsardi/Library/R/arm64/4.4/library/glue...
✓ Removed 2 packages (R 4.4.1, main: /Users/gaborcsardi/Library/R/arm64/4.4/library)

Removing a package deletes its directory in the library, which is what R CMD REMOVE and remove.packages() do as well.

Package names are case sensitive, as they are in R, and every package named must be installed in the library: if one of them is not, then rig removes none of them. Naming the same package twice is not an error, it is removed once.

rig does not check whether another installed package needs the one being removed. Use rig pkg list to see what is installed, and --json for machine readable output about what was removed.

The base packages that ship with R (base, stats, utils, …) are part of the R installation, and R does not work without them, so rig refuses to remove them unless --force is also given.

Which library

By default rig removes the packages from the default library of the default R version, i.e. the library that rig library default reports, and the one R installs packages into.

--library (-l) selects another library. It takes either the name of a library of the R version, as rig library list prints them, or the path of a library directory:

rig pkg remove --library myproject cli
rig pkg remove --library /usr/lib/R/site-library cli

A path is used as it is, so it does not need to belong to an R version rig manages, and rig does not need an R version at all to remove packages from it.

--r-version (-r) selects the library of another R version, instead of the default one, as it does for the rig library commands. It has no effect when --library is a path.

In admin mode the site and system libraries of an R installation belong to the administrator, so removing a package from them needs sudo (an administrator account on Windows). Your own user library never does. To remove a whole library, with all the packages in it, use rig library rm instead.

Usage

rig pkg remove [OPTIONS] <package>...

Arguments

<package>...: packages to remove

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--force: Remove base packages as well, which R itself needs
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
-l, --library <library>: Library name or path, instead of the default library
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
-r, --r-version <r-version>: R version to operate on, instead of the default
--user: Run in user mode (overrides RIG_MODE and config)

`rig pkg tree`

Show everything a package needs, directly or indirectly, as a tree: the same closure rig pkg deps --recursive lists in a flat table, laid out by the shape of the dependency graph.

dplyr 1.1.4 — 13 direct, 30 total
├── R (>= 3.5.0) [D]
├── cli 3.6.4 (>= 3.4.0)
│   ├── R (>= 3.4) [D]
│   └── utils
├── lifecycle 1.0.4 (>= 1.0.3)
│   ├── cli 3.6.4 (>= 3.4.0) (*)
│   └── rlang 1.1.6 (>= 1.1.0)
│       └── R (>= 3.5.0) [D]
└── vctrs 0.6.5 (>= 0.6.4)
    └── cpp11 0.5.2 [L]
[Suggests]
└── tidyr 1.3.1 (>= 1.3.0)
    └── cpp11 0.5.2 (>= 0.4.0) [L] (*)

The first line names the package version, how many dependencies it has directly and how many distinct packages there are in the whole tree. Each line below names a package, the version currently on CRAN, and the version requirement it is needed with, if it has one.

--version asks about a specific version, including versions CRAN has archived. --json gives machine readable output, as one nested object. rig proj tree shows the same tree for the dependencies a project declares.

Reading the tree

A package that several others need is expanded only once, under its first occurrence; later occurrences are a single line marked (*), meaning “its dependencies are above”. This is also what makes dependency cycles end on their own.

A mark at the end of a line says how the package is needed; Imports is the common case and is not marked.

[D] — a Depends, so the package is attached, not merely loaded.
[L] — a LinkingTo, so this package is compiled against it.
[DL] — both.

Dependencies are listed with R first, then grouped by dependency type, in the order R lists the fields in, and by name within a type. R and the base packages, e.g. utils, are shown with their version requirement but without a version of their own, as they are part of R; --no-base leaves them out altogether. A package that is not in the repositories is shown with ? for its version.

By default rig follows the hard dependencies only. --dev adds Suggests and Enhances, in their own [Suggests] and [Enhances] sections. As in rig pkg deps, --dev applies to the queried package only, so these sections only ever appear at the top of the tree.

Inverting the tree

--why <package> (alias --explain) inverts the tree: the named package is the root and the tree grows towards the packages that need it, down to the queried package, which becomes a leaf.

glue 1.8.1 — 4 direct dependents, 5 total
├── dplyr 1.2.1 (needs >= 1.3.2)
├── pillar 1.11.1
│   └── dplyr 1.2.1 (needs >= 1.9.0)
└── vctrs 0.7.3
    ├── dplyr 1.2.1 (needs >= 0.7.1)
    └── pillar 1.11.1 (needs >= 0.5.0) (*)

Each line says how that package needs the one above it, hence needs; the [D], [L], [S] and [E] marks describe the same edge. [S] and [E] take the place of the [Suggests] and [Enhances] sections, which in an inverted tree would be one line deep inside it.

--why searches the tree only, not the repositories, so --version, --dev and --no-base apply as above, and a package that is not in the tree is an error.

Usage

rig pkg tree [OPTIONS] <package>

Arguments

<package>: package to show the dependency tree of

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--dev: Include dev (development) dependencies
-h, --help: Print help (see a summary with ‘-h’)
--json: JSON output
--no-base: Leave out R and the base packages
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user: Run in user mode (overrides RIG_MODE and config)
-v, --version <version>: package version to use (default: latest)
--why <PACKAGE>: Invert the tree: show what pulls this package in [aliases: explain]