Skip to contents

Several environments

Source: vignettes/articles/environments.qmd

A Pixi project can have several environments, each with its own R and packages. For example:

  • An environment with an older R, to check your code still runs there.
  • An environment with extra packages for tests or documentation, which the project itself doesn’t need.

Features and environments

Environments are made of features: named sets of packages. The default feature holds what pixi_add() adds, and every environment includes it, unless you leave it out.

To make an environment, add packages to a feature, which creates it, then make an environment of that feature:

library(rpix)

pixi_add("testthat", feature = "test")
pixi_add_environment("test", features = "test")

The feature has to exist before an environment can use it, so add its packages first.

Another version of R

An environment with R 4.4, next to the default one with the latest R, in one step:

pixi_add_environment("r44", r_version = "4.4")

This adds a feature r44 with R 4.4 and the project’s packages, from the default feature, and makes an environment of it, then installs it. The packages are copied by name, so the environment gets the versions built for R 4.4, which Pixi then pins in pixi.toml. rpix comes along if the project has it, so pixi_switch() and the .Rprofile work there too.

  • The default feature is left out: it has the project’s R, and an environment can’t have two. conda-ecosystem-user-package-isolation, which keeps your personal R library out, is copied too; without it, R 4.4 could load packages from your personal library that were built for another R, and crash.

  • Packages built from source (from GitHub, or CRAN packages that aren’t on conda-forge) aren’t copied, as their entries pin the project’s R. rpix lists them; add them with pixi_add(..., feature = "r44").

  • If R 4.4 can’t have all the packages, e.g. an old R and a package that’s newer than it, rpix leaves pixi.toml as it was and shows Pixi’s error. Then build the environment by hand, with the packages it can have:

    pixi_add(c("r-base=4.4", "dplyr"), feature = "r44")
pixi_add_environment("r44", features = "r44", default_feature = FALSE)

    pixi_add_environment() adds the isolation to the r44 feature then too.

Keeping environments in step

Environments in the same solve group get the same versions of the packages they share. That suits a test environment, which should test the versions the project uses:

pixi_add_environment("test", features = "test", solve_group = "default", overwrite = TRUE)

Environments with different versions of R can’t share a solve group.

Using an environment

Switch your IDE to an environment’s R with:

See Using rpix with an IDE for what that does in each IDE. From a terminal, pixi run --environment r44 R starts that R.

To move your IDE to it, run pixi_switch("r44"), or pixi_switch() to pick it from a menu. In RStudio this starts a new RStudio with that R; in Positron it opens the interpreter picker; in VS Code it points the R extension at that R. See Using rpix with an IDE.

Or run a function in it from the R you’re in, and get the result back:

pixi_r(function() R.version.string, environment = "r44")
#> [1] "R version 4.4.3 (2025-02-28)"

The function runs in a new R, so it doesn’t see your variables: pass what it needs as arguments, with args = list(...).

In Positron, each environment shows up as its own R in the interpreter picker, e.g. “R 4.4.3 (Pixi: r44)”.

See the project’s environments, and their features, with:

Developing a package

For the whole workflow, from setting up to CI, see Developing a package.

For a package, pixi_import_description() adds what the package needs from its DESCRIPTION: Depends and Imports to the project, and Suggests to a test environment, in the same solve group as the default one:

Packages that aren’t on conda-forge or bioconda are listed, and left out.

Checking it on several versions of R

use_pixi_check_matrix() adds an environment for each version of R, with the package’s dependencies and what the tests and R CMD check need:

use_pixi_check_matrix(c("4.3", "4.4", "4.5"))

Then run the tests in all of them, and see the results side by side:

pixi_check_matrix()
#> ── Tests ──────────────────────────────────────────────────────────
#> ✔ r43  R 4.3.3: 120 passed, 0 failed, 2 skipped, 0 warnings (41 s)
#> ✖ r44  R 4.4.3: 119 passed, 1 failed, 2 skipped, 0 warnings (38 s)
#> ✔ r45  R 4.5.3: 120 passed, 0 failed, 2 skipped, 0 warnings (37 s)

what = "check" runs R CMD check instead, and parallel = TRUE runs in all environments at once. What each run printed is in the output column.

Checking the minimum versions

DESCRIPTION says which versions a package needs at least, such as cli (>= 3.0), but those are easy to get wrong when nothing tests them. minimum = TRUE adds a minimum environment, with R at the version Depends asks for, and each dependency at the lowest version its constraint allows:

use_pixi_check_matrix(minimum = TRUE)
pixi_check_matrix("minimum")

A dependency without a minimum gets the oldest version on conda-forge for that R, which rpix points out. The Suggests are there too, for the tests and examples: those without a minimum get at least the version the project has, as they aren’t what’s tested. Only versions on conda-forge count, and for old builds, conda-forge’s record of their own dependencies is sometimes looser than their DESCRIPTION; then R refuses to load one even though Pixi installed it. That’s worth knowing when a failure doesn’t seem to be about your package.

Install an environment with pixi_install(environment = "r44"), or all of them with pixi_install(all = TRUE). pixi run also installs an environment the first time it’s used.