Skip to content

Install

Classes

RuntimeStatus dataclass

Immutable snapshot of current runtime state.

RuntimeManifest dataclass

Runtime bundle manifest (from manifest.json).

SystemInfo dataclass

Immutable system environment snapshot.

Functions

install_runtime(install_rtools=False)

Install prebuilt brmspy runtime bundle for fast setup.

Downloads and activates a precompiled runtime containing: - R packages (brms, cmdstanr, dependencies) - Compiled CmdStan binary - Complete environment ready for immediate use

This reduces setup time from ~30 minutes to ~1 minute by avoiding compilation. Available for specific platform/R version combinations.

This function reconfigures the running embedded R session to use an isolated library environment from downloaded binaries. It does not mix or break the default library tree already installed in the system.

Parameters:

Name Type Description Default
install_rtools bool

Installs RTools (windows only) if they cant be found. WARNING: Modifies system path and runs the full rtools installer.

 False

Returns:

Type Description
bool

Path if installation succeeded, None otherwise

Raises:

Type Description
RuntimeError

If prebuilt binaries not available for this platform
Notes

Platform Support: Prebuilt binaries are available for: - Linux: x86_64, glibc >= 2.27, g++ >= 9 - macOS: x86_64 and arm64, clang >= 11 - Windows: x86_64 with Rtools

R Version: Runtime includes all R packages, so they must match your R installation's major.minor version (e.g., R 4.3.x).

System Fingerprint: Runtime is selected based on: - Operating system (linux/macos/windows) - CPU architecture (x86_64/arm64) - R version (major.minor)

Example: linux-x86_64-r4.3

See Also

install_brms : Main installation function

get_brms_version()

Get installed brms R package version.

Returns:

Type Description
str

Version object or None

Raises:

Type Description
ImportError

If brms is not installed

Examples:

from brmspy import brms
version = brms.get_brms_version()
print(f"brms version: {version}")

get_active_runtime()

Get path to currently active prebuilt runtime.

Returns:

Type Description
Path or None

Path to active runtime directory, or None if not configured
Notes

Returns None if: - No runtime configured in config file - Config file doesn't exist - Config file is corrupted

Examples:

from brmspy import get_active_runtime

runtime_path = get_active_runtime()
if runtime_path and runtime_path.exists():
    print(f"Active runtime: {runtime_path}")
else:
    print("No active runtime configured")

install_brms(*, use_prebuilt=False, install_rtools=False, brms_version=None, cmdstanr_version=None, install_rstan=True, install_cmdstanr=True, rstan_version=None, activate=True, **kwargs)

Install brms R package, optionally cmdstanr and CmdStan compiler, or rstan.

WINDOWS WARNING: DO NOT run this if you have

Parameters:

Name Type Description Default
brms_version str

brms version: "latest", "2.23.0", or ">= 2.20.0"

 "latest"
repo str | None

Extra CRAN repository URL

 None
install_cmdstanr bool

Whether to install cmdstanr and build CmdStan compiler

 True
install_rstan bool

Whether to install rstan (alternative to cmdstanr)

 False
cmdstanr_version str

cmdstanr version: "latest", "0.8.1", or ">= 0.8.0"

 "latest"
rstan_version str

rstan version: "latest", "2.32.6", or ">= 2.32.0"

 "latest"
use_prebuilt bool

Uses fully prebuilt binaries for cmdstanr and brms and their dependencies. Ignores system R libraries and uses the latest brms and cmdstanr available for your system. Requires R>=4 and might not be compatible with some older systems or missing toolchains. Can reduce setup time by 50x.

 False
install_rtools bool

Installs RTools (windows only) if they cant be found. WARNING: Modifies system path and runs the full rtools installer. Use with caution!

 False

Examples:

Basic installation:

from brmspy import brms
brms.install_brms()
Install specific version:

brms.install_brms(brms_version="2.23.0")

Use rstan instead of cmdstanr:

brms.install_brms(install_cmdstanr=False, install_rstan=True)

Fast installation with prebuilt binaries: ```python brms.install_brms(use_prebuilt=True)

activate_runtime(runtime_path=None)

Activate a runtime by mutating R environment.

Parameters:

Name Type Description Default
runtime_path Path or str or None

Path to runtime directory. If None, uses last active runtime from config.

 None

Raises:

Type Description
ValueError

If runtime_path is None and no config exists.
FileNotFoundError

If runtime directory doesn't exist.
RuntimeError

If runtime structure is invalid or activation fails.
Notes

Side effects of activation:

  • Stores original R environment for later restoration
  • Unloads brms/cmdstanr/rstan if loaded
  • Sets R .libPaths() to runtime's Rlib/
  • Sets cmdstanr path to runtime's cmdstan/
  • Saves runtime_path to ~/.brmspy/config.json
  • Invalidates cached R package singletons

deactivate_runtime()

Deactivate current runtime and restore original R environment.

Raises:

Type Description
RuntimeError

If no runtime is currently active.
Notes

Side effects of deactivation:

  • Unloads brms/cmdstanr/rstan if loaded
  • Restores original .libPaths()
  • Restores original cmdstan path
  • Clears active_runtime from config
  • Invalidates cached R package singletons

status()

Query current runtime status without side effects.

Returns:

Type Description
RuntimeStatus

Dataclass with comprehensive state information including:

  • Active runtime path and activation state
  • System fingerprint and toolchain info
  • Prebuilt compatibility and availability
  • Installed brms/cmdstanr/rstan versions

find_local_runtime()

Find an installed runtime matching the current system fingerprint.

Uses system_fingerprint() to compute the current system identity and searches the local runtime store for a matching runtime directory.

Returns:

Type Description
Path or None

Path to the matching runtime root directory if found, otherwise None.
Notes

This function is a pure lookup: it does not install, activate, or modify any runtime state.