py_require: Declare Python Requirements

In rstudio/reticulate: Interface to 'Python'

Declare Python Requirements

Description

py_require() allows you to declare Python requirements for the R session, including Python packages, any version constraints on those packages, and any version constraints on Python itself. Reticulate can then automatically create and use an ephemeral Python environment that satisfies all these requirements.

Usage

py_require(
  packages = NULL,
  python_version = NULL,
  ...,
  exclude_newer = NULL,
  action = c("add", "remove", "set")
)

Arguments

packages	A character vector of Python packages to be available during the session. These can be simple package names like "jax" or names with version constraints like "jax[cpu]>=0.5".
python_version	A character vector of Python version constraints (e.g., "3.10" or ">=3.9,<3.13,!=3.11").
...	Reserved for future extensions; must be empty.
exclude_newer	Restricts package versions to those published before a specified date. This offers a lightweight alternative to freezing package versions, helping guard against Python package updates that break a workflow. Once exclude_newer is set, only the set action can override it.
action	Determines how py_require() processes the provided requirements. Options are: add: Adds the entries to the current set of requirements. remove: Removes__exact_ matches from the requirements list. For example, if "numpy==2.2.2" is in the list, passing "numpy" with action = "remove" will not remove it. Requests to remove nonexistent entries are ignored. set: Clears all existing requirements and replaces them with the provided ones. Packages and the Python version can be set independently.

Details

Reticulate will only use an ephemeral environment if no other Python installation is found earlier in the Order of Discovery. You can also force reticulate to use an ephemeral environment by setting Sys.setenv(RETICULATE_USE_MANAGED_VENV = "yes").

The ephemeral virtual environment is not created until the user interacts with Python for the first time in the R session, typically when import() is first called.

If py_require() is called with new requirements after reticulate has already initialized an ephemeral Python environment, a new ephemeral environment is activated on top of the existing one. Once Python is initialized, only adding packages is supported—removing packages, changing the Python version, or modifying exclude_newer is not possible.

Calling py_require() without arguments returns a list of the currently declared requirements.

R packages can also call py_require() (e.g., in .onLoad() or elsewhere) to declare Python dependencies. The print method for py_require() displays the Python dependencies declared by R packages in the current session.

Note

Reticulate uses uv to resolve Python dependencies. Many uv options can be customized via environment variables, as described here. For example:

• If temporarily offline, set Sys.setenv(UV_OFFLINE=1).

• To use a different index: Sys.setenv(UV_INDEX = "https://download.pytorch.org/whl/cpu").

• To allow resolving a prerelease dependency: Sys.setenv(UV_PRERELEASE="allow").

rstudio/reticulate documentation built on Feb. 17, 2025, 8:38 a.m.