rv

rv is a new way to manage and install your R packages in a reproducible, fast, and declarative way.

Documentation Site

Documentation site with examples, cookbooks, and more detailed instructions available at: https://a2-ai.github.io/rv-docs/

Quick Start

Installation

curl -sSL https://raw.githubusercontent.com/A2-ai/rv/refs/heads/main/scripts/install.sh | bash
rv --version

Initialize Your First Project

# Create a new project directory
mkdir my-analysis && cd my-analysis

# Create an R script
cat > analysis.R << 'EOF'
library(dplyr)
library(ggplot2)
data <- readr::read_csv("data.csv")
EOF

# Initialize rv (automatically scans R files and sets up PPM repositories)
rv init

# Install all dependencies
rv sync

That's it! rv init automatically:

• ✅ Scanned your R files for library(), require(), and pkg::function references
• ✅ Configured fast PPM CRAN and Bioconductor repositories
• ✅ Detected your R version
• ✅ Created rv.lock for reproducibility
• ✅ Set up project-local library in rv/library/

How it works

rv has several top level commands to provide the user with as much flexibility as possible. The primary commands are:

rv init  # initialize a new project (automatically scans R files for dependencies)
rv plan  # preview what will occur if sync is run
rv sync  # synchronize the library, config file, and lock file

Initializing a Project

The rv init command sets up a new project with intelligent defaults:

# Basic initialization in current directory
rv init

# Initialize in a specific directory
rv init my-project

# Initialize with conda environment
rv init --condaenv my-env

# Initialize with specific R version
rv init --r-version 4.3

Automatic Dependency Discovery: rv init automatically scans all .R and .r files in your project directory (recursively) and extracts package dependencies from:

• library(pkg) calls
• require(pkg) calls
• pkg::function namespace references

Default Repositories: By default, rv init configures fast binary repositories:

• PPM CRAN: https://packagemanager.posit.co/cran/latest
• PPM Bioconductor: https://packagemanager.posit.co/bioc/latest

Use --no-repositories to skip default repositories if you prefer to configure your own.

The subsequent actions of these commands are controlled by a configuration file that specifies a desired project state by specifying the R version, repositories, and dependencies the project uses. Additionally, specific package and repository level customizations can be specified.

For example, a configuration file generated by rv init:

[project]
name = "my-project"
r_version = "4.4"

repositories = [
    { alias = "posit", url = "https://packagemanager.posit.co/cran/latest" },
    { alias = "bioc", url = "https://packagemanager.posit.co/bioc/latest" },
]

# Automatically extracted from your R scripts
dependencies = [
    "dplyr",
    "ggplot2",
    "readr"
]

Or with conda environment:

[project]
name = "my-project"
r_version = "4.4"
conda_env = "my-project-env"

repositories = [
    { alias = "posit", url = "https://packagemanager.posit.co/cran/latest" },
    { alias = "bioc", url = "https://packagemanager.posit.co/bioc/latest" },
]

dependencies = [
    "dplyr",
    "ggplot2"
]

Using with Conda Environments

rv can integrate seamlessly with conda/mamba/micromamba environments. This allows you to use conda-managed R installations while letting rv handle R package management.

Quick Start with Conda

# Initialize with conda environment
rv init --condaenv myenv

# Use an existing conda environment
rv sync --condaenv myenv

# Or auto-create a new environment with --auto-create
rv sync --condaenv myproject-env --auto-create

Configuration File Example

You can specify the conda environment during initialization or in your rproject.toml:

[project]
name = "my conda project"
r_version = "4.4.1"
conda_env = "my-project-env"

repositories = [
    { alias = "posit", url = "https://packagemanager.posit.co/cran/latest" },
    { alias = "bioc", url = "https://packagemanager.posit.co/bioc/latest" },
]

dependencies = [
    "dplyr",
    "ggplot2",
    "tidyr"
]

When using a conda environment, rv will:

• Install packages directly to the conda environment's R library ({conda_env}/lib/R/library)
• Use the conda-managed R installation
• Save the environment and library path to your configuration for future use

This approach combines the best of both worlds: conda for R runtime management and rv for reproducible R package management.

Advanced Initialization

# Initialize with specific R version
rv init --r-version 4.3.0

# Initialize with custom repositories
rv init --no-repositories
rv configure repository add cran --url https://cran.r-project.org

# Initialize and add additional packages manually
rv init --add tidyr purrr

# Initialize with conda and auto-create environment
rv init --condaenv myproject --r-version 4.4

Automatic Package Discovery

The rv init command intelligently discovers your R package dependencies by:

1. Scanning all R files: Recursively searches .R and .r files in your project
2. Extracting package references: Finds packages from:
   • library("pkg") or library('pkg') or library(pkg)
   • require("pkg") or require('pkg') or require(pkg)
   • pkg::function() namespace calls
3. Filtering built-in packages: Removes R base packages (base, utils, stats, etc.) and recommended packages (MASS, Matrix, etc.)
4. Deduplication: Automatically removes duplicate package references

This means you can run rv init on an existing R project and get a working rproject.toml without manually listing dependencies!

Running rv sync will synchronize the library, lock file, and configuration file by installing dplyr, ggplot2, any dependencies those packages require, and the suggested packages for ggplot2. Running rv plan will give you a preview of what rv sync will do.

Additional example projects with more configurations can be found in the example_projects directory of this repository.

Installation

See the installation documentation for information on how to install rv.

Usage

See the usage documentation for information on how to use rv and how to configure it with the rproject.toml file.

Contributing

Getting started

To get started with the development of rv, you'll need:

• Rust
• and optionally Just

After installing Rust, you can build the project by running:

just run <args>
// or
cargo run --features=cli --release -- ...

e.g. just run sync or just run add --dry-run.

If you'd like to install the current version of the project as a binary, you can run:

just install
// or
cargo install --path . --features cli

Unit testing

Run the unit tests with:

just test
// or
cargo test --features=cli

Snapshot testing

Snapshots require R version 4.4.x.