Title:	Reproducible Data Science Environments with 'Nix'
Version:	0.16.0
Description:	Simplifies the creation of reproducible data science environments using the 'Nix' package manager, as described in Dolstra (2006) <ISBN 90-393-4130-3>. The included ‘rix()' function generates a complete description of the environment as a 'default.nix' file, which can then be built using ’Nix'. This results in project specific software environments with pinned versions of R, packages, linked system dependencies, and other tools. Additional helpers make it easy to run R code in 'Nix' software environments for testing and production.
License:	GPL (≥ 3)
URL:	https://docs.ropensci.org/rix/
BugReports:	https://github.com/ropensci/rix/issues
Depends:	R (≥ 2.10)
Imports:	codetools, curl, jsonlite, sys, utils
Suggests:	knitr, rmarkdown, testthat
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-04-24 08:40:11 UTC; brodriguesco
Author:	Bruno Rodrigues [aut, cre], Philipp Baumann [aut], David Watkins [rev] (David reviewed the package (v. 0.9.1) for rOpenSci, see <https://github.com/ropensci/software-review/issues/625>), Jacob Wujiciak-Jens [rev] (Jacob reviewed the package (v. 0.9.1) for rOpenSci, see <https://github.com/ropensci/software-review/issues/625>), Richard J. Acton [ctb], Jordi Rosell [ctb], Elio Campitelli [ctb], László Kupcsik [ctb], Michael Heming [ctb]
Maintainer:	Bruno Rodrigues <bruno@brodrigues.co>
Repository:	CRAN
Date/Publication:	2025-04-24 09:10:02 UTC

List available dates.

Description

List available dates.

Usage

available_dates()

Value

A character vector containing the available dates

Examples

available_dates()

Return data frame with R, Bioc versions and supported platforms

Description

Return data frame with R, Bioc versions and supported platforms

Usage

available_df()

Value

A data frame

Examples

available_dates()

List available R versions from the rstats-on-nix fork of Nixpkgs

Description

List available R versions from the rstats-on-nix fork of Nixpkgs

Usage

available_r()

Value

A character vector containing the available R versions.

Examples

available_r()

ga_cachix Build an environment on GitHub Actions and cache it on Cachix

Description

ga_cachix Build an environment on GitHub Actions and cache it on Cachix

Usage

ga_cachix(cache_name, path_default)

Arguments

Details

This function puts a .yaml file inside the ⁠.github/workflows/⁠ folders on the root of your project. This workflow file will use the projects default.nix file to generate the development environment on GitHub Actions and will then cache the created binaries in Cachix. Create a free account on Cachix to use this action. Refer to vignette("z-binary_cache") for detailed instructions. Make sure to give read and write permissions to the GitHub Actions bot.

Value

Nothing, copies file to a directory.

Examples

## Not run: 
ga_cachix("my-cachix", path_default = "default.nix")

## End(Not run)

Create a startup script to launch an editor inside of a Nix shell

Description

Create a startup script to launch an editor inside of a Nix shell

Usage

make_launcher(editor, project_path)

Arguments

Details

This function will write a launcher to start an IDE inside of a Nix shell. With a launcher, you only need to execute it instead of first having to drop into the shell using nix-shell and then type the command to run the IDE. For security reasons, this script is not executable upon creation, so you need to make it executable first by running ⁠chmod +x start-editor.sh⁠ (replace editor with whichever editor you use). You don’t need this launcher if you use direnv; see vignette("e-configuring-ide") for more details.

Value

Nothing, writes a script.

Examples

available_dates()

Invoke shell command nix-build from an R session

Description

Invoke shell command nix-build from an R session

Usage

nix_build(
  project_path = getwd(),
  message_type = c("simple", "quiet", "verbose"),
  args = NULL
)

Arguments

Details

This function is a wrapper for the nix-build command-line interface. Users can supply any flags supported by nix-build via the args parameter. If no custom arguments are provided, only the project directory is passed.

Value

Integer of the process ID (PID) of the nix-build shell command launched, if the nix_build() call is assigned to an R object. Otherwise, it will be returned invisibly.

Examples

## Not run: 
  # Run nix-build with default arguments (project directory)
  nix_build()

  # Run nix-build with custom arguments
  nix_build(args = c("--max-jobs", "2", "--quiet"))

## End(Not run)

read_renv_lock

Description

Reads renv.lock if it exists and can be parsed as json.

Usage

read_renv_lock(renv_lock_path = "renv.lock")

Arguments

Value

the result of reading renv.lock with jsonlite::read_json

renv2nix

Description

renv2nix

Usage

renv2nix(
  renv_lock_path = "renv.lock",
  project_path,
  return_rix_call = FALSE,
  method = c("fast", "accurate"),
  override_r_ver = NULL,
  ...
)

Arguments

Details

In order for this function to work properly, we recommend not running it inside the same folder as an existing {renv} project. Instead, run it from a new, empty directory which path you pass to project_path, and use renv_lock_path to point to the renv.lock file in the original {renv} folder. We recommend that you start from an empty folder to hold your new Nix project, and copy the renv.lock file only (not any of the other files and folders generated by {renv}) and then call renv2nix() there. For more details, see vignette("f-renv2nix").

Value

Nothing, this function is called for its side effects only, unless return_rix_call = TRUE in which case an unevaluated call to rix() is returned

Examples

## Not run: 
# if the lock file is in another folder
renv2nix(
  renv_lock_path = "path/to/original/renv_project/renv.lock",
  project_path = "path/to/rix_project"
)
# you could also copy the renv.lock file in the folder of the Nix
# project (don’t copy any other files generated by `{renv}`)
renv2nix(
  renv_lock_path = "path/to/rix_project/renv.lock",
  project_path = "path/to/rix_project"
)

## End(Not run)

renv_lock_r_ver

Description

renv_lock_r_ver

Usage

renv_lock_r_ver(renv_lock, override_r_ver = NULL)

Arguments

Value

a length 1 character vector with the version of R recorded in renv.lock

Examples

## Not run: 
rix(r_ver = renv_lock_r_ver())

## End(Not run)

renv_remote_pkgs

Description

Construct a list to be passed the git_pkgs argument of rix The list returned contains the information necessary to have nix attempt to build the packages from their external repositories.

Usage

renv_remote_pkgs(renv_lock_remote_pkgs, host = NULL)

Arguments

Value

a list of lists with three elements named: "package_name", "repo_url", "commit"

Examples

## Not run: 
renv_remote_pkgs(read_renv_lock()$Packages)

## End(Not run)

Generate a Nix expression that builds a reproducible development environment

Description

Generate a Nix expression that builds a reproducible development environment

Usage

rix(
  r_ver = NULL,
  date = NULL,
  r_pkgs = NULL,
  system_pkgs = NULL,
  git_pkgs = NULL,
  local_r_pkgs = NULL,
  tex_pkgs = NULL,
  py_conf = NULL,
  ide = "none",
  project_path,
  overwrite = FALSE,
  print = FALSE,
  message_type = "simple",
  shell_hook = NULL,
  ignore_remotes_cache = FALSE
)

Arguments

Details

This function will write a default.nix and an .Rprofile in the chosen path. Using the Nix package manager, it is then possible to build a reproducible development environment using the nix-build command in the path. This environment will contain the chosen version of R and packages, and will not interfere with any other installed version (via Nix or not) on your machine. Every dependency, including both R package dependencies but also system dependencies like compilers will get installed as well in that environment.

It is possible to use environments built with Nix interactively, either from the terminal, or using an interface such as RStudio. If you want to use RStudio, set the ide argument to "rstudio". Please be aware that for macOS, RStudio is only available starting from R version 4.4.3 or from the 2025-02-28. As such, you may want to use another editor on macOS if you need to use an environment with an older version of R. To use Visual Studio Code (or Codium), set the ide argument to "code" or "codium" respectively, which will add the {languageserver} R package to the list of R packages to be installed by Nix in that environment. It is also possible to use Positron by setting the ide argument to "positron". Setting the ide argument to an editor will install it from Nix, meaning that each of your projects can have a dedicated IDE (or IDE version). "radian" and "rserver" are also options.

Instead of using Nix to install an IDE, you can also simply use the one you have already installed on your system, with the exception of RStudio which must be managed by Nix to "see" Nix environments. Positron must also be heavily configured to work with Nix shells, so we recommend installing it using Nix. To use an editor that you already have installed on your system, set ide = "none" and refer to the vignette("e-configuring-ide") for more details on how to set up your editor to work with Nix shells.

Packages to install from GitHub or Gitlab must be provided in a list of 3 elements: "package_name", "repo_url" and "commit". To install several packages, provide a list of lists of these 3 elements, one per package to install. It is also possible to install old versions of packages by specifying a version. For example, to install the latest version of {AER} but an old version of {ggplot2}, you could write: r_pkgs = c("AER", "ggplot2@2.2.1"). Note however that doing this could result in dependency hell, because an older version of a package might need older versions of its dependencies, but other packages might need more recent versions of the same dependencies. If instead you want to use an environment as it would have looked at the time of {ggplot2}'s version 2.2.1 release, then use the Nix revision closest to that date, by setting r_ver = "3.1.0", which was the version of R current at the time. This ensures that Nix builds a completely coherent environment. For security purposes, users that wish to install packages from GitHub/GitLab or from the CRAN archives must provide a security hash for each package. {rix} automatically precomputes this hash for the source directory of R packages from GitHub/Gitlab or from the CRAN archives, to make sure the expected trusted sources that match the precomputed hashes in the default.nix are downloaded, but only if Nix is installed. If you need to generate an expression with such packages, but are working on a system where you can't install Nix, consider generating the expression using a continuous integration service, such as GitHub Actions.

Note that installing packages from Git or old versions using the "@" notation or local packages, does not leverage Nix's capabilities for dependency solving. As such, you might have trouble installing these packages. If that is the case, open an issue on {rix}'s GitHub repository.

If GitHub packages have dependencies on GitHub as well, {rix} will attempt to generate the correct expression, but we highly recommend you read the vignette("z-advanced-topic-handling-packages-with-remote-dependencies") Vignette.

By default, the Nix shell will be configured with "en_US.UTF-8" for the relevant locale variables (LANG, LC_ALL, LC_TIME, LC_MONETARY, LC_PAPER, LC_MEASUREMENT). This is done to ensure locale reproducibility by default in Nix environments created with rix(). If there are good reasons to not stick to the default, you can set your preferred locale variables via ⁠options(rix.nix_locale_variables = list(LANG = "de_CH.UTF-8", <...>)⁠ and the aforementioned locale variable names.

It is possible to use ⁠"bleeding-edge⁠" or ⁠"frozen-edge⁠" as the value for the r_ver argument. This will create an environment with the very latest R packages. ⁠"bleeding-edge⁠" means that every time you will build the environment, the packages will get updated. This is especially useful for environments that need to be constantly updated, for example when developing a package. In contrast, ⁠"frozen-edge⁠" will create an environment that will remain stable at build time. So if you create a default.nix file using ⁠"bleeding-edge⁠", each time you build it using nix-build that environment will be up-to-date. With ⁠"frozen-edge⁠" that environment will be up-to-date on the date that the default.nix will be generated, and then each subsequent call to nix-build will result in the same environment. "bioc-devel" is the same as "bleeding-edge", but also adds the development version of Bioconductor. "r-devel" is the same as bleeding edge, but with the R development version instead of the latest stable version and "r-devel-bioc-devel" is the same as "r-devel" but with Bioconductor on the development version. We highly recommend you read the vignette titled "z - Advanced topic: Understanding the rPackages set release cycle and using bleeding edge packages".

Value

Nothing, this function only has the side-effect of writing two files: default.nix and .Rprofile in the working directory. default.nix contains a Nix expression to build a reproducible environment using the Nix package manager, and .Rprofile ensures that a running R session from a Nix environment cannot access local libraries, nor install packages using install.packages() (nor remove nor update them).

Examples

## Not run: 
# Build an environment with the latest version of R available from Nixpkgs
# and the dplyr and ggplot2 packages
rix(
  r_ver = "latest-upstream",
  r_pkgs = c("dplyr", "ggplot2"),
  system_pkgs = NULL,
  git_pkgs = NULL,
  local_r_pkgs = NULL,
  ide = "code",
  project_path = path_default_nix,
  overwrite = TRUE,
  print = TRUE,
  message_type = "simple",
  shell_hook = NULL,
  ignore_remotes_cache = FALSE
)

## End(Not run)

Initiate and maintain an isolated, project-specific, and runtime-pure R setup via Nix.

Description

Creates an isolated project folder for a Nix-R configuration. rix::rix_init() also adds, appends, or updates with or without backup a custom .Rprofile file with code that initializes a startup R environment without system's user libraries within a Nix software environment. Instead, it restricts search paths to load R packages exclusively from the Nix store. Additionally, it makes Nix utilities like nix-shell available to run system commands from the system's RStudio R session, for both Linux and macOS.

Usage

rix_init(
  project_path,
  rprofile_action = c("create_missing", "create_backup", "overwrite", "append"),
  message_type = c("simple", "quiet", "verbose")
)

Arguments

Details

Enhancement of computational reproducibility for Nix-R environments:

The primary goal of rix::rix_init() is to enhance the computational reproducibility of Nix-R environments during runtime. Concretely, if you already have a system or user library of R packages (if you have R installed through the usual means for your operating system), using rix::rix_init() will prevent Nix-R environments to load packages from the user library which would cause issues. Notably, no restart is required as environmental variables are set in the current session, in addition to writing an .Rprofile file. This is particularly useful to make with_nix() evaluate custom R functions from any "Nix-to-Nix" or "System-to-Nix" R setups. It introduces two side-effects that take effect both in a current or later R session setup:

1. Adjusting R_LIBS_USER path: By default, the first path of R_LIBS_USER points to the user library outside the Nix store (see also base::.libPaths()). This creates friction and potential impurity as R packages from the system's R user library are loaded. While this feature can be useful for interactively testing an R package in a Nix environment before adding it to a .nix configuration, it can have undesired effects if not managed carefully. A major drawback is that all R packages in the R_LIBS_USER location need to be cleaned to avoid loading packages outside the Nix configuration. Issues, especially on macOS, may arise due to segmentation faults or incompatible linked system libraries. These problems can also occur if one of the (reverse) dependencies of an R package is loaded along the process.

2. Make Nix commands available when running system commands from RStudio: In a host RStudio session not launched via Nix (nix-shell), the environmental variables from ⁠~/.zshrc⁠ or ⁠~/.bashrc⁠ may not be inherited. Consequently, Nix command line interfaces like nix-shell might not be found. The .Rprofile code written by rix::rix_init() ensures that Nix command line programs are accessible by adding the path of the "bin" directory of the default Nix profile, "/nix/var/nix/profiles/default/bin", to the PATH variable in an RStudio R session.

These side effects are particularly recommended when working in flexible R environments, especially for users who want to maintain both the system's native R setup and utilize Nix expressions for reproducible development environments. This init configuration is considered pivotal to enhance the adoption of Nix in the R community, particularly until RStudio in Nixpkgs is packaged for macOS. We recommend calling rix::rix_init() prior to comparing R code ran between two software environments with rix::with_nix().

rix::rix_init() is called automatically by rix::rix() when generating a default.nix file, and when called by rix::rix() will only add the .Rprofile if none exists. In case you have a custom .Rprofile that you wish to keep using, but also want to benefit from what rix_init() offers, manually call it and set the rprofile_action to "append".

Value

Nothing, this function only has the side-effect of writing a file called ".Rprofile" to the specified path.

See Also

with_nix()

Examples

## Not run: 
# create an isolated, runtime-pure R setup via Nix
project_path <- "./sub_shell"
if (!dir.exists(project_path)) dir.create(project_path)
rix_init(
  project_path = project_path,
  rprofile_action = "create_missing",
  message_type = c("simple")
)

## End(Not run)

setup_cachix Setup up the rstats-on-nix binary repository

Description

setup_cachix Setup up the rstats-on-nix binary repository

Usage

setup_cachix(nix_conf_path = "~/.config/nix")

Arguments

Details

This function edits ⁠~/.config/nix/nix.conf⁠ to add the rstats-on-nix public cache as a substituter. The rstats-on-nix public cache, hosted on Cachix, contains many prebuild binaries of R and R packages for x86_64 Linux and macOS (Intel architectures for packages released before 2021 and Apple Silicon from 2021 onwards). This function automatically performs a backup of ⁠~/.config/nix/nix.conf⁠, or creates one if there is no nix.conf file. If you installed Nix by following the instructions provided in the "Getting started" vignette and also followed the instructions to install Cachix and configure the cache, you don't need to run this. This function is useful in mainly two cases: if you somehow mess up ⁠~/.config/nix/nix.conf⁠ and need to generate a new one from scratch, or if you're using Nix inside Docker, write a ⁠RUN Rscript -e 'rix::setup_cachix()'⁠ statement to configure the cache there. Because Docker runs using root by default no need to install the cachix client to configure the cache, running setup_cachix() is enough. See the 'z - Advanced topic: Using Nix inside Docker' vignette for more details.

Value

Nothing; changes a file in the user's home directory.

Examples

## Not run: 
setup_cachix()

## End(Not run)

tar_nix_ga Run a {targets} pipeline on GitHub Actions.

Description

tar_nix_ga Run a {targets} pipeline on GitHub Actions.

Usage

tar_nix_ga()

Details

This function puts a .yaml file inside the ⁠.github/workflows/⁠ folders on the root of your project. This workflow file will use the projects default.nix file to generate the development environment on GitHub Actions and will then run the projects {targets} pipeline. Make sure to give read and write permissions to the GitHub Actions bot.

Value

Nothing, copies file to a directory.

Examples

## Not run: 
tar_nix_ga()

## End(Not run)

Evaluate function in R or shell command via nix-shell environment

Description

This function needs an installation of Nix. with_nix() has two effects to run code in isolated and reproducible environments.

1. Evaluate a function in R or a shell command via the nix-shell environment (Nix expression for custom software libraries; involving pinned versions of R and R packages via Nixpkgs)

2. If no error, return the result object of expr in with_nix() into the current R session.

Usage

with_nix(
  expr,
  program = c("R", "shell"),
  project_path = ".",
  message_type = c("simple", "quiet", "verbose")
)

Arguments

Details

with_nix() gives you the power of evaluating a main function expr and its function call stack that are defined in the current R session in an encapsulated nix-R session defined by Nix expression (default.nix), which is located in at a distinct project path (project_path).

with_nix() is very convenient because it gives direct code feedback in read-eval-print-loop style, which gives a direct interface to the very reproducible infrastructure-as-code approach offered by Nix and Nixpkgs. You don't need extra efforts such as setting up DevOps tooling like Docker and domain specific tools like {renv} to control complex software environments in R and any other language. It is for example useful for the following purposes.

1. test compatibility of custom R code and software/package dependencies in development and production environments

2. directly stream outputs (returned objects), messages and errors from any command line tool offered in Nixpkgs into an R session.

3. Test if evolving R packages change their behavior for given unchanged R code, and whether they give identical results or not.

with_nix() can evaluate both R code from a nix-R session within another nix-R session, and also from a host R session (i.e., on macOS or Linux) within a specific nix-R session. This feature is useful for testing the reproducibility and compatibility of given code across different software environments. If testing of different sets of environments is necessary, you can easily do so by providing Nix expressions in custom .nix or default.nix files in different subfolders of the project.

rix_init() is run automatically to generate a custom .Rprofile file for the subshell in project_dir. The defaults in that file ensure that only R packages from the Nix store, that are defined in the subshell .nix file are loaded and system's libraries are excluded.

To do its job, with_nix() heavily relies on patterns that manipulate language expressions (aka computing on the language) offered in base R as well as the {codetools} package by Luke Tierney.

Some of the key steps that are done behind the scene:

1. recursively find, classify, and export global objects (globals) in the call stack of expr as well as propagate R package environments found.

2. Serialize (save to disk) and deserialize (read from disk) dependent data structures as .Rds with necessary function arguments provided, any relevant globals in the call stack, packages, and expr outputs returned in a temporary directory.

3. Use pure nix-shell environments to execute a R code script reconstructed catching expressions with quoting; it is launched by commands like this via {sys} by Jeroen Ooms: ⁠nix-shell --pure --run "Rscript --vanilla"⁠.

Value

• if program = "R", R object returned by function given in expr when evaluated via the R environment in nix-shell defined by Nix expression.

• if program = "shell", list with the following elements:

  • status: exit code

  • stdout: character vector with standard output

  • stderr: character vector with standard error of expr command sent to a command line interface provided by a Nix package.

Examples

## Not run: 
# create an isolated, runtime-pure R setup via Nix
project_path <- "./sub_shell"
rix_init(
  project_path = project_path,
  rprofile_action = "create_missing"
)
# generate nix environment in `default.nix`
rix(
  r_ver = "4.2.0",
  project_path = project_path
)
# evaluate function in Nix-R environment via `nix-shell` and `Rscript`,
# stream messages, and bring output back to current R session
out <- with_nix(
  expr = function(mtcars) nrow(mtcars),
  program = "R", project_path = project_path,
  message_type = "simple"
)

# There no limit in the complexity of function call stacks that `with_nix()`
# can possibly handle; however, `expr` should not evaluate and
# needs to be a function for `program = "R"`. If you want to pass the
# a function with arguments, you can do like this
get_sample <- function(seed, n) {
  set.seed(seed)
  out <- sample(seq(1, 10), n)
  return(out)
}

out <- with_nix(
  expr = function() get_sample(seed = 1234, n = 5),
  program = "R",
  project_path = ".",
  message_type = "simple"
)

## You can also attach packages with `library()` calls in the current R
## session, which will be exported to the nix-R session.
## Other option: running system commands through `nix-shell` environment.

## End(Not run)