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>=1.0
#|   - tidyr
#| r-version: ">= 4.0"
#| isolated: true
#| exclude-newer: "2024-01-15"

library(dplyr)
library(tidyr)

1 + 1

Run the file through ir:

$ ir run script.R
$ ir run --vanilla script.R
$ ir run --exclude-newer 2024-01-15 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.
  • 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 CRAN from the Posit Package Manager snapshot for that date. When no R selector is set, it also selects the latest R major.minor version available on 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. 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 version specs include pkg, pkg>=1.0, and pkg==1.2. 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. 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.

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.

#!/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>=1.1' --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.