Skip to content
rv docs

First rv project

This section will walk through how to start with your first rv project, from creating an rv project, to familiarizing yourself with the configuration file, to installing your first package.

Start a new project

Section titled “Start a new project”

To start a new project, use rv init:

Terminal window
rv init hello_world

rv init will create generate the following project structure:

  • Directoryhello_world/
    • Directoryrv/
      • Directorylibrary/
        • …
      • Directoryscripts/
        • activate.R sets .libPaths and options(“repos”)
        • rvr.R sets up .rv environment
      • .gitignore ignores library/
    • .Rprofile used to run rv/scripts/* to set up project
    • rproject.toml

We will first focus on the rproject.toml file, as it is what users primarily interact with, while the other files will be discussed in additional sections.

The rproject.toml is the default name for rv’s configuration file, which allows users to declare and configure their desired project environment. During project initialization, the rproject.toml is pre-populated with information found in your R session.

Below is what the rproject.toml in the project initialized above may look like:

rproject.toml
[project]
name = "hello_world"
r_version = "4.4"


# A list of repositories to fetch packages from. Order matters: we will try to get a package from each repository in order.
# The alias is only used in this file if you want to specifically require a dependency to come from a certain repository.
# Example: { alias = "PPM", url = "https://packagemanager.posit.co/cran/latest" },
repositories = [
    {alias = "PPM", url = "https://packagemanager.posit.co/cran/latest"},
]


# A list of packages to install and any additional configuration
# Examples:
    # "dplyr",
    # {name = "dplyr", repository = "CRAN"},
    # {name = "dplyr", git = "https://github.com/tidyverse/dplyr.git", tag = "v1.1.4"},
dependencies = [


]

Config File Basics

Section titled “Config File Basics”

Before continuing, let’s familiarize ourselves with the main components of the config file:

name

Section titled “name”

A name for your project. Defaults to the name of the directory, but has no requirements.

r_version

Section titled “r_version”

The R version for the project. During rv init, this is set by default to the version found on the path.

WARNING: If using RStudio/Positron, the R version on the path does not always match the version selected.

repositories

Section titled “repositories”

The repositories dependencies are sourced from unless otherwise specified. During rv init defaults to the repositories set in options("repos") when possible.

dependencies

Section titled “dependencies”

The main element of the file. This is where you specify the packages (known as dependencies) used in your project, and options about how and from where they are installed.

Installing a Package

Section titled “Installing a Package”

Instead of individual, iterative package installation, rv takes a holistic approach. Dependencies are “synchronized” across the config file, lock file, and project library to ensure the project is in the expected, working state at all times.

Therefore, to install packages from the config file, the command is rv sync.

To install our first package using rv, we will edit the config file’s dependencies section to include dplyr:

rproject.toml
[project]
name = "my-rv-project"
r_version = "4.4"


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


dependencies = [
    "dplyr"
]

Then we will run rv sync, which will install dplyr and all of its dependencies:

Terminal window
% rv sync
+ cli (3.6.5, binary from https://packagemanager.posit.co/cran/latest) in 530ms
+ dplyr (1.1.4, binary from https://packagemanager.posit.co/cran/latest) in 509ms
+ fansi (1.0.6, binary from https://packagemanager.posit.co/cran/latest) in 421ms
+ generics (0.1.4, binary from https://packagemanager.posit.co/cran/latest) in 317ms
+ glue (1.8.0, binary from https://packagemanager.posit.co/cran/latest) in 382ms
+ lifecycle (1.0.4, binary from https://packagemanager.posit.co/cran/latest) in 379ms
+ magrittr (2.0.3, binary from https://packagemanager.posit.co/cran/latest) in 360ms
+ pillar (1.10.2, binary from https://packagemanager.posit.co/cran/latest) in 458ms
+ pkgconfig (2.0.3, binary from https://packagemanager.posit.co/cran/latest) in 287ms
+ R6 (2.6.1, binary from https://packagemanager.posit.co/cran/latest) in 339ms
+ rlang (1.1.6, binary from https://packagemanager.posit.co/cran/latest) in 553ms
+ tibble (3.2.1, binary from https://packagemanager.posit.co/cran/latest) in 407ms
+ tidyselect (1.2.1, binary from https://packagemanager.posit.co/cran/latest) in 374ms
+ utf8 (1.2.5, binary from https://packagemanager.posit.co/cran/latest) in 427ms
+ vctrs (0.6.5, binary from https://packagemanager.posit.co/cran/latest) in 476ms
+ withr (3.0.2, binary from https://packagemanager.posit.co/cran/latest) in 401ms

Additionally, a lock file is generated within the project, containing information about each package installed, including the version, dependencies, and source, making the project directory look like the following:

  • Directoryhello_world/
    • Directoryrv/
      • Directorylibrary/
        • …
      • Directoryscripts/
        • activate.R
        • rvr.R
      • .gitignore
    • .Rprofile
    • rproject.toml
    • rv.lock

For more information on how the lock file impacts package installation, see the resolution section