Package {sysreqr}

Title:	Preflight Checks for 'R' Package System Requirements
Version:	0.1.0
Description:	Helps users on 'Linux' (and, where applicable, 'macOS') find the system packages they need before installing 'R' packages from source. Queries maintained system requirement sources, reports missing system packages, and generates installation commands, 'Dockerfile' snippets, 'GitHub Actions' steps, administrator request templates, and diagnostic reports from failed installation logs.
License:	GPL-3
URL:	https://github.com/choxos/sysreqR
BugReports:	https://github.com/choxos/sysreqR/issues
Depends:	R (≥ 4.1)
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0), withr
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/Needs/website:	pkgdown
Encoding:	UTF-8
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-06-05 16:08:45 UTC; choxos
Author:	Ahmad Sofi-Mahmudi [aut, cre]
Maintainer:	Ahmad Sofi-Mahmudi <a.sofimahmudi@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-11 11:50:02 UTC

sysreqr: Preflight Checks for R Package System Requirements

Description

sysreqr helps users on Linux (and, where applicable, macOS) discover the system packages they need before installing R packages from source. It queries maintained system requirement sources, reports missing system packages, and generates installation commands, Dockerfile snippets, GitHub Actions steps, administrator request templates, and diagnostic reports from failed installation logs.

Details

The package has zero required dependencies. It uses only base R at run time. testthat, knitr, rmarkdown, and withr are listed in Suggests only for development needs (tests and vignettes); they are never loaded when end users call package functions.

Main entry points

• Preflight checks: check_packages(), check_library(), check_project(), detect_project_packages().

• Platform detection: detect_platform(), detect_package_manager(), resolve_platform().

• Output generators: install_command(), dockerfile(), github_actions(), admin_request().

• Diagnostics: diagnose_log(), check_error(), diagnose_failed_packages().

• Posit Package Manager: ppm_platforms(), check_ppm(), ppm_repo(), ppm_sysreqs(), use_ppm().

• Setup advice: setup_advice(), explain().

• File writers: write_json(), write_report(), write_install_script(), write_dockerfile_snippet(), as_install_plan().

Package options

The following options influence behavior. Set them with options() or in .Rprofile.

sysreqr.ppm_base_url

Posit Package Manager base URL. Defaults to "https://packagemanager.posit.co".

sysreqr.ppm_get

Optional function used in place of the PPM HTTP client. Mainly for tests.

sysreqr.pak_pkg_sysreqs

Optional function used in place of pak::pkg_sysreqs(). Mainly for tests.

sysreqr.installed_system_packages

Optional character vector or named logical vector used to override installed-package detection. Mainly for tests.

sysreqr.timeout

Numeric timeout (seconds) for Posit Package Manager HTTP calls. Defaults to the larger of getOption("timeout") and 60.

Learning more

See vignette("preflight-setup", package = "sysreqr") for a beginner workflow, vignette("diagnosing-failures", package = "sysreqr") for log diagnosis, vignette("linux-fundamentals", package = "sysreqr") for a GNU/Linux primer, vignette("docker-and-ci", package = "sysreqr") for container and CI workflows, and vignette("faq", package = "sysreqr") for common questions.

Author(s)

Maintainer: Ahmad Sofi-Mahmudi a.sofimahmudi@gmail.com (ORCID)

Authors:

• Ahmad Sofi-Mahmudi a.sofimahmudi@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/choxos/sysreqR

• Report bugs at https://github.com/choxos/sysreqR/issues

Create an administrator request

Description

Produces a plain-text message that a user without root access can send to their system administrator. The message lists missing system packages, which R packages need them, and a suggested install command.

Usage

admin_request(x, platform = NULL, ...)

Arguments

Value

A plain-text administrator request.

See Also

Other commands: dockerfile(), github_actions(), install_command()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
cat(admin_request(plan))

Coerce a plan to a plain data frame

Description

Strips the sysreqr_plan class and attributes, returning a plain data.frame. Equivalent to as.data.frame() on a plan, but provided as a verb form for users who prefer that style.

Usage

as_data_frame(x)

Arguments

Value

A data frame without the sysreqr_plan class.

See Also

Other plan: is_sysreqr_plan(), print.sysreqr_plan()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
df <- as_data_frame(plan)
inherits(df, "sysreqr_plan")
inherits(df, "data.frame")

Return backend install plan data

Description

Converts a plan into a structured list suitable for downstream tooling (other R code, deployment scripts, or CI). The fields are platform, backend, pre_install, install, post_install, and packages.

Usage

as_install_plan(x)

Arguments

Value

A list with commands and plan data.

See Also

Other output: write_dockerfile_snippet(), write_install_script(), write_json(), write_report()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
as_install_plan(plan)

Check the most recent install error for likely system requirements

Description

Convenience wrapper around diagnose_log(). When text is NULL (the default), the most recent R error message is read from base::geterrmessage().

Usage

check_error(
  text = NULL,
  platform = NULL,
  backend = c("auto", "bundled", "ppm", "pak"),
  repo = "cran",
  check_installed = TRUE
)

Arguments

Value

A sysreqr_plan.

See Also

Other diagnose: diagnose_failed_packages(), diagnose_log()

Examples

check_error(
  text = "ERROR: configuration failed for package 'xml2'",
  platform = "ubuntu-22.04",
  backend = "bundled"
)

Check system requirements for installed R packages

Description

Reads the package names from one or more R library paths and resolves their system requirements. Useful for auditing an existing R installation.

Usage

check_library(
  packages = NULL,
  library = .libPaths()[1],
  platform = NULL,
  backend = c("bundled", "auto", "ppm", "pak")
)

Arguments

Value

A sysreqr_plan.

See Also

Other preflight: check_packages(), check_project(), detect_project_packages()

Examples

# Offline, with an explicit package list and the bundled backend:
check_library(
  packages = c("xml2", "curl"),
  platform = "ubuntu-22.04",
  backend = "bundled"
)

Check system requirements for R packages

Description

Resolves the system packages an R package needs on a given Linux platform and returns them in a structured plan. The "auto" backend prefers the offline bundled database on apt platforms, then Posit Package Manager, then pak.

Usage

check_packages(
  packages,
  platform = NULL,
  backend = c("auto", "bundled", "ppm", "pak"),
  repo = "cran",
  dependencies = NA,
  upgrade = TRUE,
  check_installed = TRUE
)

Arguments

Value

A sysreqr_plan.

See Also

check_project(), check_library(), diagnose_log().

Other preflight: check_library(), check_project(), detect_project_packages()

Examples

plan <- check_packages(c("xml2", "curl"), platform = "ubuntu-22.04")
plan

install_command(plan)

Check Posit Package Manager support

Description

Reports whether a platform is currently served by Posit Package Manager and whether it has system requirement metadata and binary packages.

Usage

check_ppm(platform = NULL, base_url = ppm_default_base_url())

Arguments

Value

A list with the matched platform and Package Manager status.

See Also

Other ppm: ppm_platforms(), ppm_repo(), ppm_sysreqs(), use_ppm()

Examples

check_ppm("ubuntu-22.04")
check_ppm("fedora-40")

Check system requirements for a project

Description

Convenience wrapper around detect_project_packages() and check_packages().

Usage

check_project(
  path = ".",
  include_suggests = FALSE,
  platform = NULL,
  backend = c("auto", "bundled", "ppm", "pak"),
  ...
)

Arguments

Value

A sysreqr_plan.

See Also

Other preflight: check_library(), check_packages(), detect_project_packages()

Examples

project <- file.path(tempdir(), "demo-project")
dir.create(project, showWarnings = FALSE)
writeLines(
  c("Package: demo", "Imports: xml2"),
  file.path(project, "DESCRIPTION")
)
check_project(project, platform = "ubuntu-22.04", backend = "bundled")

Detect the platform package manager

Description

Returns the name of the operating system package manager for a platform: "apt", "dnf", "yum", "zypper", "apk", or "brew".

Usage

detect_package_manager(platform = NULL)

Arguments

Value

A package manager name such as "apt" or "dnf".

See Also

Other platform: detect_platform(), resolve_platform()

Examples

detect_package_manager("ubuntu-22.04")
detect_package_manager("fedora-40")
detect_package_manager("opensuse156")

Detect the current platform

Description

Detects the host operating system and, on Linux, parses ⁠/etc/os-release⁠. On macOS, queries sw_vers. Returns a structured platform object used by the rest of the package. When os_release is supplied and exists, the file is parsed even on macOS or Windows; this makes fixture-driven testing practical.

Usage

detect_platform(os_release = "/etc/os-release")

Arguments

Value

An object of class sysreqr_platform (a list).

See Also

Other platform: detect_package_manager(), resolve_platform()

Examples

platform <- detect_platform()
platform$distro

# Reproducible reads from a fixture file:
fixture <- system.file(
  "extdata", "os-release-fedora-40",
  package = "sysreqr",
  mustWork = FALSE
)
if (nzchar(fixture)) detect_platform(os_release = fixture)

Detect R packages used by a project

Description

Inspects a project directory for the R packages it uses. The detection priority is:

Usage

detect_project_packages(path = ".", include_suggests = FALSE)

Arguments

Details

1. renv.lock (the Packages map),

2. DESCRIPTION (Depends, Imports, LinkingTo, and optionally Suggests),

3. .R, .Rmd, .qmd, and NAMESPACE files (looking for library(), require(), requireNamespace(), and pkg::fun references; line comments are ignored).

Value

A character vector of package names.

See Also

Other preflight: check_library(), check_packages(), check_project()

Examples

project <- file.path(tempdir(), "demo-project")
dir.create(project, showWarnings = FALSE)
writeLines(
  c("Package: demo", "Imports: xml2, curl"),
  file.path(project, "DESCRIPTION")
)
detect_project_packages(project)

Diagnose failed R packages

Description

Resolves the system requirements for a set of R packages that the user already knows failed to install. Useful when an install was attempted outside R, or when the log was lost.

Usage

diagnose_failed_packages(
  packages,
  platform = NULL,
  backend = c("auto", "bundled", "ppm", "pak"),
  repo = "cran",
  check_installed = TRUE
)

Arguments

Value

A sysreqr_plan.

See Also

Other diagnose: check_error(), diagnose_log()

Examples

diagnose_failed_packages(
  c("xml2", "curl"),
  platform = "ubuntu-22.04",
  backend = "bundled"
)

Diagnose an R package installation log

Description

Scans an installation log for common compiler and linker errors and for R-level "configuration failed" and "non-zero exit status" patterns, then resolves those failed packages back to their system requirements.

Usage

diagnose_log(
  path = NULL,
  text = NULL,
  platform = NULL,
  backend = c("auto", "bundled", "ppm", "pak"),
  repo = "cran",
  check_installed = TRUE
)

diagnose_install_log(
  path = NULL,
  text = NULL,
  platform = NULL,
  backend = c("auto", "bundled", "ppm", "pak"),
  repo = "cran",
  check_installed = TRUE
)

Arguments

Details

The function combines two paths:

1. Direct log-pattern matching against a curated list of header and linker error messages.

2. Failed package extraction plus a back-end lookup of those package names.

Confidence levels are "high" for direct pattern matches and pak/PPM lookups, and "medium" for bundled fallback data and inferred package requirements.

Value

A sysreqr_plan with likely system package fixes.

See Also

Other diagnose: check_error(), diagnose_failed_packages()

Examples

log <- paste(
  "fatal error: libxml/parser.h: No such file or directory",
  "ERROR: configuration failed for package 'xml2'",
  sep = "\n"
)
plan <- diagnose_log(text = log, platform = "ubuntu-22.04")
plan

Generate Dockerfile lines

Description

Produces a Dockerfile RUN snippet that installs the system packages a plan needs. On apt platforms the output uses the standard ⁠apt-get update && apt-get install -y --no-install-recommends ... && rm -rf /var/lib/apt/lists/*⁠ pattern.

Usage

dockerfile(x, platform = NULL, missing_only = TRUE, ...)

Arguments

Value

A single Dockerfile snippet.

See Also

Other commands: admin_request(), github_actions(), install_command()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
cat(dockerfile(plan))

Explain system requirements

Description

Prints a short, friendly explanation for each system package an R package needs and the command to install it. Useful for teaching and for emails to less-experienced collaborators.

Usage

explain(x, platform = NULL, ...)

Arguments

Value

A character vector of explanation lines, invisibly.

See Also

Other setup: print.sysreqr_setup_advice(), setup_advice()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
explain(plan)

Generate a GitHub Actions snippet

Description

Produces a GitHub Actions YAML step that installs the system packages a plan needs. gha() is a short alias.

Usage

github_actions(x, platform = NULL, missing_only = TRUE, ...)

gha(x, platform = NULL, missing_only = TRUE, ...)

Arguments

Value

A YAML snippet.

See Also

Other commands: admin_request(), dockerfile(), install_command()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
cat(github_actions(plan))
identical(gha(plan), github_actions(plan))

Generate an installation command

Description

Translates a plan (or a package vector that can be resolved to a plan) into shell commands appropriate for the platform's package manager.

Usage

install_command(
  x,
  platform = NULL,
  sudo = TRUE,
  update = TRUE,
  missing_only = TRUE,
  ...
)

Arguments

Value

A character vector of shell commands.

See Also

Other commands: admin_request(), dockerfile(), github_actions()

Examples

plan <- check_packages(c("xml2", "curl"), platform = "ubuntu-22.04")
install_command(plan)
install_command(plan, sudo = FALSE, update = FALSE)

Test whether an object is a sysreqr plan

Description

Test whether an object is a sysreqr plan

Usage

is_sysreqr_plan(x)

Arguments

Value

TRUE if x inherits from "sysreqr_plan".

See Also

Other plan: as_data_frame(), print.sysreqr_plan()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
is_sysreqr_plan(plan)
is_sysreqr_plan(data.frame(x = 1))

List Posit Package Manager platforms

Description

Queries the Posit Package Manager ⁠/__api__/status⁠ endpoint and returns a data frame of supported distributions.

Usage

ppm_platforms(base_url = ppm_default_base_url())

Arguments

Value

A data frame of platform records reported by Package Manager.

See Also

Other ppm: check_ppm(), ppm_repo(), ppm_sysreqs(), use_ppm()

Examples

ppm_platforms()

Build a Posit Package Manager repository URL

Description

Constructs a Linux binary repository URL for the given platform, CRAN repository alias, and snapshot.

Usage

ppm_repo(
  platform = NULL,
  repo = "cran",
  snapshot = "latest",
  base_url = ppm_default_base_url()
)

Arguments

Value

A repository URL.

See Also

Other ppm: check_ppm(), ppm_platforms(), ppm_sysreqs(), use_ppm()

Examples

ppm_repo(platform = "ubuntu-22.04")
ppm_repo(platform = "ubuntu-26.04", snapshot = "2026-04-01")

Query Package Manager system requirements

Description

Queries the Posit Package Manager ⁠/sysreqs⁠ endpoint for the given packages and platform, and normalizes the response into a sysreqr_plan. If the API call fails, the function falls back to the bundled database and records the failure in the "fallback_error" attribute of the returned plan.

Usage

ppm_sysreqs(
  packages = NULL,
  all = FALSE,
  platform = NULL,
  repo = "cran",
  base_url = ppm_default_base_url(),
  check_installed = TRUE
)

Arguments

Value

A sysreqr_plan.

See Also

Other ppm: check_ppm(), ppm_platforms(), ppm_repo(), use_ppm()

Examples

ppm_sysreqs(c("xml2", "curl"), platform = "ubuntu-22.04")

Print a sysreqr plan

Description

Print a sysreqr plan

Usage

## S3 method for class 'sysreqr_plan'
print(x, ...)

Arguments

Value

x, invisibly.

See Also

Other plan: as_data_frame(), is_sysreqr_plan()

Print setup advice

Description

Print setup advice

Usage

## S3 method for class 'sysreqr_setup_advice'
print(x, ...)

Arguments

Value

x, invisibly.

See Also

Other setup: explain(), setup_advice()

Resolve a platform specification

Description

Accepts a NULL, a sysreqr_platform object, or a short string and returns a fully normalized platform object. Strings can be the ⁠<distro>-<version>⁠ shorthand ("ubuntu-22.04", "debian-12") or a codename alias ("jammy", "noble", "resolute", "bookworm", "trixie").

Usage

resolve_platform(platform = NULL)

Arguments

Value

A platform list with class "sysreqr_platform".

See Also

Other platform: detect_package_manager(), detect_platform()

Examples

resolve_platform("ubuntu-22.04")
resolve_platform("resolute")
resolve_platform("bookworm")

Get beginner setup advice for R package installation on Linux

Description

Produces a practical checklist for users who are new to R on GNU/Linux. It recommends binary package repositories where available, explains when R Project operating system repositories are relevant, lists source build tools, and can add package-specific system requirements. It never runs sudo, edits the system R configuration, or changes operating system repositories; the user remains in control.

Usage

setup_advice(
  packages = NULL,
  platform = NULL,
  backend = c("auto", "bundled", "ppm", "pak"),
  repo = "cran",
  check_installed = TRUE,
  include_r_project_repo = TRUE,
  script = NULL
)

Arguments

Value

A sysreqr_setup_advice object.

See Also

Other setup: explain(), print.sysreqr_setup_advice()

Examples

advice <- setup_advice(
  "xml2",
  platform = "ubuntu-22.04",
  backend = "bundled"
)
print(advice)


# Write a reviewable shell script:
setup_advice(
  c("xml2", "curl"),
  platform = "ubuntu-22.04",
  backend = "bundled",
  script = tempfile(fileext = ".sh")
)

Configure Package Manager repository options

Description

Emits or installs the R code lines that point options(repos) at a Posit Package Manager binary repository. With dry_run = TRUE (the default), the lines are returned without touching any file, so the user can review them before applying. When dry_run = FALSE, path must be supplied explicitly.

Usage

use_ppm(
  scope = c("user", "project"),
  platform = NULL,
  repo = "cran",
  dry_run = TRUE,
  path = NULL
)

Arguments

Value

The configuration lines, invisibly when written.

See Also

Other ppm: check_ppm(), ppm_platforms(), ppm_repo(), ppm_sysreqs()

Examples

use_ppm("user", platform = "ubuntu-22.04", dry_run = TRUE)

# Write to a throwaway .Rprofile under tempdir():
use_ppm(
  "user",
  platform = "ubuntu-22.04",
  dry_run = FALSE,
  path = file.path(tempdir(), ".Rprofile")
)

Write a Dockerfile snippet

Description

Writes the output of dockerfile() to a file so it can be appended to an existing Dockerfile or included verbatim.

Usage

write_dockerfile_snippet(plan, path)

Arguments

Value

path, invisibly.

See Also

Other output: as_install_plan(), write_install_script(), write_json(), write_report()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
write_dockerfile_snippet(plan, file.path(tempdir(), "Dockerfile.sysreqs"))

Write an install script

Description

Writes a POSIX-shell install script. The script begins with ⁠#!/usr/bin/env sh⁠ and set -eu and is marked executable.

Usage

write_install_script(plan, path)

Arguments

Value

path, invisibly.

See Also

Other output: as_install_plan(), write_dockerfile_snippet(), write_json(), write_report()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
write_install_script(plan, file.path(tempdir(), "install-sysreqs.sh"))

Write a sysreqr plan as JSON

Description

Serializes the plan data frame to JSON.

Usage

write_json(plan, path)

Arguments

Value

path, invisibly.

See Also

Other output: as_install_plan(), write_dockerfile_snippet(), write_install_script(), write_report()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
write_json(plan, file.path(tempdir(), "sysreqs.json"))

Write a Markdown report

Description

Produces a human-readable Markdown report describing the platform, selected backend, R packages checked, system packages needed, and a suggested install command.

Usage

write_report(plan, path)

Arguments

Value

path, invisibly.

See Also

Other output: as_install_plan(), write_dockerfile_snippet(), write_install_script(), write_json()

Examples

plan <- check_packages("xml2", platform = "ubuntu-22.04")
write_report(plan, file.path(tempdir(), "SYSREQS.md"))