Scripts

ir run executes R scripts whose package metadata is embedded at the top of the file. The metadata block is YAML, with each line prefixed by #| after an optional shebang.

#!/usr/bin/env -S ir run
#| packages:
#|   - dplyr
#|   - tidyr==1.3.1
#| r-version: ">= 4.3"
#| isolated: true
#| exclude-newer: "2024-02-01"

airquality |> tidyr::drop_na(Ozone) |> dplyr::count(Month)

This records a last-known-good environment: tidyr is pinned to the version tested with the script, while the snapshot date selects dplyr and the transitive dependencies.

Run the file through ir:

$ ir run script.R
$ ir run --vanilla script.R
$ ir run --exclude-newer 2024-02-01 script.R
$ ir run --refresh script.R
$ echo 'print(commandArgs(TRUE))' | ir run - stdin-arg
$ ./script.R

Frontmatter Metadata

The script frontmatter supports:

• packages: package refs resolved with pak.
• r-version: an optional R version requirement selected from installed versions reported by rig. Requirements that can match more than one R minor select released versions; use devel to select R-devel explicitly.
• python-packages: optional Python package specs resolved with reticulate’s uv environment helper.
• python-version: an optional Python version requirement.
• python-exclude-newer: an optional Python package snapshot date.
• isolated: true disables the user library for the run.
• exclude-newer: an optional YYYY-MM-DD date that resolves the default CRAN and Bioconductor repositories from Posit Package Manager snapshots for that date. When no R selector is set, it also selects the latest R major.minor version released by that date. When r-version can match more than one R minor, it limits selection to minor versions released by that date.

Snapshot date precedence is --exclude-newer, then IR_EXCLUDE_NEWER, then frontmatter exclude-newer. R selection precedence is command line, then environment, then frontmatter r-version. Use --rscript or IR_RSCRIPT when you need a machine-local Rscript override. An exact r-version or explicit Rscript selection remains authoritative when exclude-newer is also set. Frontmatter rscript is rejected. Command-line and environment values are trimmed before use. An empty --exclude-newer or IR_EXCLUDE_NEWER overrides frontmatter exclude-newer and resolves latest packages. Future snapshot dates also resolve latest packages.

Supported package specs include pkg and exact versions such as pkg==1.2. pak does not currently resolve minimum-version refs such as pkg>=1.2; use an exact version or exclude-newer instead. Source refs are resolved with pak and then passed through to renv, including GitHub, GitLab, Bitbucket, git, URL, and local package refs in forms both tools accept. GitHub packages should use package refs such as github::owner/repo@ref or github::owner/repo/subdir@ref, not browser URLs copied from GitHub. Local packages may be written as local::path, as a bare file-system path in pak-supported forms such as ./path, or with a package prefix such as mypkg=local::C:/path for Windows absolute paths. Set IR_NO_LOCAL_SOURCES to a nonempty value to prevent an install from using direct or transitive packages resolved from local package refs, file: URLs, or file: repositories. Existing materialised libraries may be reused regardless of where their packages were originally resolved. packages must be a YAML sequence; each sequence entry is one package ref. Omit packages, use packages: [], or use packages: null when no package refs are needed. Unknown keys are ignored after YAML parsing, so future metadata such as sys-reqs can be present before ir supports it.

Bioconductor packages

Bioconductor packages use their bare package names. pak selects the Bioconductor release compatible with the selected R.

$ ir run --with BiocGenerics -e 'library(BiocGenerics)'

Python environments

Use python-packages or python-version to ask ir run for a Python environment before launching the script. ir resolves the environment with reticulate:::uv_get_or_create_env() before launching the script:

• It activates the environment for subprocesses, like source <env>/bin/activate on Unix.
• It sets RETICULATE_PYTHON to the resolved Python executable.

Declare reticulate under packages when the R script loads reticulate. When Python metadata is absent, ir run sets RETICULATE_PYTHON=managed if RETICULATE_PYTHON is unset. This lets reticulate create its lazy managed environment from py_require() declarations made by R packages. This portable default intentionally takes precedence over reticulate’s other Python selectors. To opt out, set RETICULATE_PYTHON to a concrete interpreter before launch, or unset it in the script before configuring reticulate.

#!/usr/bin/env -S ir run
#| packages:
#|   - reticulate
#| python-packages:
#|   - pandas
#|   - matplotlib
#| python-version: "3.11"
#| exclude-newer: "2026-06-01"

library(reticulate)
pd <- import("pandas")

The activated environment also puts Python package executables on PATH:

#!/usr/bin/env -S ir run
#| python-packages:
#|   - ruff

system2("ruff", "--version")

When Python metadata is present, exclude-newer is also used during Python environment resolution unless python-exclude-newer is set. Set python-exclude-newer to null or "" to use latest Python packages while keeping exclude-newer for R.

Inline runs

Inline expressions use the same resolver and cache:

$ ir run -e '1 + 1'
$ ir run --with cli -e 'cli::cli_alert_success("works")'
$ ir run --with dplyr --with tidyr -e 'library(dplyr); library(tidyr); 1'

--with may be repeated and accepts comma-separated packages. With a script, command-line packages are merged with the script metadata; with -e, they are the only declared packages. Inline expressions and standard-input programs do not have frontmatter. Without --with, they run against an empty resolved library while user libraries remain visible unless --isolated is supplied.

Isolation

By default, ir prepends the resolved library to .libPaths() and leaves user libraries available as a fallback. Use --isolated to remove the user library for the run:

$ ir run --isolated script.R
$ ir run --isolated --with cli -e 'cli::cli_alert_success("hi")'

--isolated sets R_LIBS_USER=NULL. Site and base/system libraries remain on the path.