Get started

Overview

Understand the rpx project model and its package management workflow.

rpx manages R dependencies for packages, applications, and analysis projects. It resolves compatible package versions, records them in a lockfile, and installs them into an isolated project library.

When you develop an R package, rpx installs your package alongside its dependencies so you can use it in the project environment. For an application or analysis, a dependency-only project manages the packages your code needs without requiring the project itself to be installed as a package.

Project model

An rpx project has three related parts:

  • DESCRIPTION declares direct dependencies and their compatible version ranges.
  • rpx.lock records the exact R version, repositories, root requirements, package versions, and sources selected by the resolver.
  • The project library contains the installed package set represented by the lockfile.

Commit DESCRIPTION and rpx.lock. The project library and rpx caches are local state and should not be committed.

Use rpx commands to change dependencies so the declaration, lockfile, and library stay together:

Terminal
rpx add jsonlite
rpx add --dev testthat
rpx remove digest
rpx status

When you edit DESCRIPTION manually, regenerate the lockfile before synchronizing:

Terminal
rpx lock
rpx sync

rpx sync intentionally refuses to install when the current DESCRIPTION, repository configuration, R version, and lockfile disagree.

Run tools through rpx run when they need the project library:

Terminal
rpx run R
rpx run Rscript scripts/check.R

Project discovery

Commands can run from a project directory or one of its descendants. rpx searches upward for the nearest Git worktree, DESCRIPTION, or rpx.lock and uses that directory as the project root.

Each project receives a library identified by its filesystem path. Moving a project causes rpx to use a different project library, which can be recreated with rpx sync.

Why rrepo?

Resolving dependencies requires knowing which package versions are available and what each version depends on. CRAN's package index only provides that information for current releases. Older versions remain in source archives without a supported API for discovering and comparing them, forcing rpx to scrape archive listings and inspect package contents for dependency metadata—a significantly slower approach that cannot reliably work across mirrors.

The rrepo repository API makes package versions and dependency metadata directly available to rpx. This lets the resolver compare candidate versions before downloading package archives for installation. The same interface supports public package collections and private repositories.

To keep the packages you already use from CRAN available through this interface, we host a CRAN mirror as one of rrepo's repositories. That mirror, at https://rrepo.dev/upstream/cran, is the default repository in rpx. CRAN is the source of those packages; rrepo provides the interface for resolving and retrieving them.

Each project can use a different base repository, add other repositories, or include packages from Git. rpx also supports traditional CRAN-like repositories directly. The lockfile records the selected sources alongside the package versions.