createEnvironment: Create a new conda environment

In LTLA/basilisk.utils: Centralized Conda Installation for Bioconductor Packages

Create a new conda environment

Description

Create a new conda environment if it does not already exist in the cache/system.

Usage

createEnvironment(
  pkg,
  name,
  version,
  packages,
  cache.dir = NULL,
  ignore.cache = FALSE,
  conda = NULL,
  channels = "conda-forge",
  override.channels = TRUE,
  extra = "--quiet"
)

Arguments

pkg	String containing the name of the R package that owns this conda environment.
name	String containing the name of the environment.
version	String containing the version of the environment. Ignored for system installs.
packages	Character vector of conda packages (possibly with version specifications) to be installed in this environment.
cache.dir	String containing the location of the cache for lazily instantiated environments. If NULL, this defaults to a location returned by R_user_dir with package. Ignored for system installs.
ignore.cache	Logical scalar indicating whether to ignore cached environments if they already exist. Ignored for system installs.
conda	String containing the path to the conda command or executable. If NULL, a suitable value is obtained from find.
channels	Character vector of channels to use for conda environment creation.
override.channels	Logical scalar indicating whether to set the --override-channels option during conda environment creation.
extra	Character vector of additional arguments to pass to conda create.

Details

In general, createEnvironment should be called inside any function of a downstream package that relies on the conda environment. On its first call, it will then lazily instantiate the environment based on the specified arguments. All subsequent calls in the same or new R sessions will use the cached environments.

The version string is used to distinguish between different versions of the same name environments. This allows package developers to safely update their environments without affecting other R installations that are re-using the same cache. Older unused versions of the environment will be automatically removed over time via dir.expiry.

Note that the version string does not necessarily have to be the same as the version of the pkg package. Any version-like string is fine as long as they are compatible with package_version. In fact, having independent versions for the environments and their parent package is often more convenient, as it means that the environments don't always need to be recreated when the package is updated.

To avoid lazy evaluation, administrators of an R installation can enable system installs, see configureEnvironments for details.

Value

String containing the path to the conda environment.

Author(s)

Aaron Lun

Examples

createEnvironment(
   pkg="basilisk.utils.test",
   name="test_env",
   version="1.0.0",
   packages="hdf5"
)

# Repeated calls will just get the same environment back.
createEnvironment(
   pkg="basilisk.utils.test",
   name="test_env",
   version="1.0.0",
   packages="hdf5"
)

LTLA/basilisk.utils documentation built on June 11, 2025, 8:56 a.m.