Skip to main content

Runtime Caches

Posit Connect maintains content runtime caches containing R packages and Python environments. These caches mean that most content deploys do not need to install every package dependency; the content can reuse the compatible packages installed by an earlier deployment.

This section explains how to reset your content runtime caches and when that reset may be necessary.

Cache invalidating operations

Python and R packages are frequently compiled and linked against the installed system libraries.

Most day-to-day administration tasks can be performed without invalidating the packages installed into the runtime caches. Distribution-managed system package updates, for example, are safe; Linux distributions ensure compatibility when issuing patches.

Major systems upgrades or updates to system libraries that are not managed by the Linux distribution can cause incompatibilities with previously built Python and R packages.

The following systems maintenance operations can cause previously built Python and R packages to become incompatible with the modified system:

  1. Rebuilding Python or R.

    Custom builds of Python and R are configured with a specific set of options and are compiled against a specific set of system libraries. Changing that compilation configuration can produce Python and R binaries that are not compatible with packages installed previously.

    For example, rebuilding R to adjust its LAPACK implementation can cause package incompatibilities.

  2. Manual system library upgrade.

    Upgrading system libraries not managed by the Linux distribution can introduce package incompatibilities.

    The GDAL libraries, for example, occasionally include breaking changes. Installing a newer GDAL version can break previously installed instances of the sf R package.

    Upgrades to the BLAS libraries, can cause incompatibilities with the numpy package.

    Prefer system libraries that are available through your Linux distribution.

  3. Compiler and build-chain upgrades.

    Making major changes to the default compiler and its build-chain can prevent the use of previously built Python and R packages.

    Prefer the compiler version that is default for your Linux distribution, or choose the target compiler during initial host provisioning.

  4. Execution environment change.

    Changes to the execution environment can invalidate previously installed Python and R packages. For example, you may transition between a bare metal, virtual machine, or containerized installation.

Use our recommended workflow to clear the Posit Connect runtime caches and rebuild your deployed content to repopulate those caches.

Prerequisites

  1. An administrator account, signed in with the Posit CLI.

    You will use this account to clear the runtime caches and optionally rebuild content.

  2. A version of Python and the Posit CLI.

Workflow

Important

When you clear the runtime caches, you are removing the packages required by your deployed content. That content cannot be run until it is rebuilt and its package dependencies installed. That rebuild is automatic when the content is next run, but may take some time to complete.

Note

Resetting the content runtime caches should be an infrequent activity performed only when a systems change invalidates the existing caches. Please contact Posit customer support via the Posit support form if you have reason to regularly take this action.

Step 1: Clear runtime caches

Use the Posit CLI to enumerate and clear the R and Python runtime caches. These caches contain packages that were built and installed using your old system configuration.

These sample delete calls act on only one cache; you may need to perform multiple deletions. The command reference for posit connect system caches contains details about each command.

Before running these commands, sign in to Connect with the Posit CLI as an administrator. See Publishing from the command line for sign-in options.

Terminal
# Enumerate the caches known to your server.
posit connect system caches list

# Validate cache targeted for deletion.
posit connect system caches delete \
    --language Python \
    --version 3.9.5 \
    --dry-run

# Delete one cache.
posit connect system caches delete \
    --language Python \
    --version 3.9.5
Terminal
# Enumerate the caches known to your server.
posit connect system caches list

# Validate cache targeted for deletion.
posit connect system caches delete \
    --language Python \
    --version 3.9.5 \
    --image-name posit/connect-content:R4.6.0-python3.14.5-ubuntu-24.04-base \
    --dry-run

# Delete one cache.
posit connect system caches delete \
    --language Python \
    --version 3.9.5 \
    --image-name posit/connect-content:R4.6.0-python3.14.5-ubuntu-24.04-base

Step 2: Rebuild content

Use the Posit CLI to rebuild your most important content. After clearing the runtime caches, content is automatically rebuilt when it first runs. A preemptive rebuild means that visitors do not experience a delayed load. The rebuild is especially useful for interactive applications and APIs.

This sample workflow enumerates and rebuilds all content. You can rebuild a subset of deployed content or rebuild your most important content first. See the command references for posit connect content search and posit connect content build for options.

Terminal
# Enumerate every "published" content item and save its GUID.
posit connect content search --published | jq '.[].guid' > guids.txt

# Queue each GUID for build.
xargs printf -- '-g %s\n' < guids.txt | xargs posit connect content build add

# Build each queued content item.
posit connect content build run