Caching

rv cache’s aggressively to avoid re-compiling and re-downloading packages and repository databases that have already been used.

Within the cache, each source is its own subdirectory to ensure the correct version of the correct package is installed.

Before going into details and how to change your caching behavior, let’s first consider a quick example:

Example

In this example, we’ll start with a config file, inspect the output of rv cache, and the file tree of the cache as well.

Config File

In this config file, we have two CRAN-like repositories and one git repository.

rproject.toml

[project]
name = "rv-cache"
r_version = "4.5"

repositories = [
    {alias = "PPM", url = "https://packagemanager.posit.co/cran/2025-01-01"},
    {alias = "PPM_new", url = "https://packagemanager.posit.co/cran/latest"},
]

dependencies = [
    "fansi",
    { name = "R6", repository = "PPM_new", force_source = true },
    { name = "osinfo", git = "https://github.com/a2-ai/osinfo", branch = "main" },
]

rv cache output

The rv cache command outputs two things:

• The cache root - Which in this case is /Users/rv-user/.cache/rv
• Source subdirectories - This lists all the sources, and their corresponding subdirectories, from which packages come from. We will discuss the structure of these for each source type later on this page.

% rv cache
/Users/rv-user/.cache/rv
PPM (https://packagemanager.posit.co/cran/2025-01-01 -> c7c3cf56b9), path: /Users/rv-user/.cache/rv/c7c3cf56b9
PPM_new (https://packagemanager.posit.co/cran/latest -> f4780dda90), path: /Users/rv-user/.cache/rv/f4780dda90
Git: https://github.com/a2-ai/osinfo, source: /Users/rv-user/.cache/rv/git/8497b6723f, binary: /Users/rv-user/.cache/rv/8497b6723f/4.4/arm64/f815095b7b

Cache File Tree

The cache file structure keeps each repository, R version, architecture, and os flavor (when applicable) isolated to ensure the proper package is installed each time. Also contained for each repository binary type is a packages.bin file, referred to as the Repository Database, which contains an index of each package available in the CRAN-like repository.

• Directory/Users/rv-user/.cache/rv

  • Directoryc7c3cf56b9

    • Directory4.5/arm64

      • Directoryfansi/1.0.6/

        • fansi The unzipped, compiled package
      • packages.bin
  • Directoryf4780dda90

    • Directory4.5/arm64

      • DirectoryR6/2.6.1

        • R6 The unzipped, compiled package
      • packages.bin
    • Directorysrc

      • DirectoryR6/2.6.1

        • R6 The unzipped, source package
  • Directorygit

    • 8497b6723f Clone of the git repository to build
  • Directory8497b6723f -4.5/arm64

    • Directoryf815095b7b Git commit sha, not package version

      • osinfo The unzipped, compiled package

Cache Location

The cache follows the XDG Base Directory Specification for Unix like systems and the Known Folder Locations on Windows. Within the cache root, rv contains its cache within an rv subdirectory.

The cache root can be tuned by setting the XDG_CACHE_HOME for Unix like systems and %LOCALAPPDATA% for Windows.

For additional tunability, use the GHQC_CACHE_DIR env var.

Repository Database

CRAN-type repositories use PACKAGES files that contain information about each package present in the repository for each package distribution (i.e. source, Mac R 4.5, ubuntu-24.04 R 4.4, etc.). rv uses the source PACKAGES file and distribution’s binary PACKAGES file to create a database for the repository.

This database is cached and times out according to the PKGCACHE_TIMEOUT environment variable (default 1 hour).

Note

Currently, rv does not have a direct way to refresh the cached repository databases. To force update, you can set the PKGCACHE_TIMEOUT to 0 secs to expire the repository databases.

For example, to check if the version you expect will be installed, you can run the following command

PKGCACHE_TIMEOUT=0 rv plan

Packages

Within the rv cache, each source is its own subdirectory

The details of package caching vary based on the dependency type.

Repository

A repository cache is broken into two components: source and binaries. The binaries are also separated by their platform, a combination of R version, OS, and architecture. rv will fetch a package to be installed into your library in the following ways:

1. Use the binary package found in the cache
2. Download the binary package from the resolved source (ignored if force_source)
3. Compile the package from the cached source package
4. Download the source package from the resolved source and compile

Caution

An important caveat to the above, if a binary is present but was downloaded and not compiled from source, if a dependency indicates force_source a new source compilation will occur and replace the downloaded binary.

This is something to always consider when using force_source, packages_env_vars, and configure_args as changing the compiled binary will effect other packages using the same package binary.

Git

rv keeps a source clone of the git repository under the git subdirectory, but then also maintains compiled binaries based on the git commits used.

Url

rv keeps the downloaded package in cache, along with the compiled version if a source package. Upon re-installation of the package, the package is re-downloaded to ensure the contents match. If they do, the package currently in cache is retained, otherwise, the new version will take its place.

Local

rv does not keep local packages in the cache. Since the file is already on the system, keeping a cached version is not practical. rv does however keep track of the hash of the source file within the compiled package in the library, therefore re-installation only occurs when the source file changes.

Global Cache

The global cache feature is available as of rv v0.18.0.

The global cache is a shared cache that organizations can configure to reduce the number of copies of packages across multiple machines and projects. Instead of each project and user maintaining their own complete copy of packages, projects can link against a centralized global cache, significantly reducing disk space usage and redundant downloads.

How It Works

The global cache works in conjunction with your local cache using a multi-level caching strategy:

1. Global Cache - A shared cache (RV_GLOBAL_CACHE_DIR) that is consulted first. If a package is present in the global cache, it is referenced directly from there
2. Local Cache - Your project-specific cache (RV_CACHE_DIR) serves as a fallback for packages not found in the global cache

Linking - rv uses the same linking mechanism (hard-links, copy-on-write, or copying) to link packages from the global cache into your project, avoiding duplication

Configuration

The global cache is generally configured by system administrators. It can be set using the RV_GLOBAL_CACHE_DIR environment variable to point to a shared location accessible to all users and machines.

For example, an administrator might configure:

export RV_GLOBAL_CACHE_DIR=/mnt/shared/rv-cache

This allows all users and projects on the organization to benefit from a shared pool of pre-compiled packages, reducing network bandwidth and storage costs while maintaining isolation through the local cache layer.