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.
py_require(
packages = NULL,
python_version = NULL,
...,
exclude_newer = NULL,
action = c("add", "remove", "set")
)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". Pip style syntax for installing
from local files or a git repository is also supported (see details).
A character vector of Python version constraints
(e.g., "3.10" or ">=3.9,<3.13").
Reserved for future extensions; must be empty.
Limit 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. Accepts strings formatted as RFC 3339 timestamps (e.g.,
"2006-12-02T02:07:43Z") and local dates in the same format (e.g.,
"2006-12-02") in your system's configured time zone. Once exclude_newer
is set, only the set action can override it.
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. Requests to remove nonexistent entries are
ignored. For example, if "numpy==2.2.2" is in the list, passing "numpy"
with action = "remove" will not remove it.
set: Clears all existing requirements and replaces them with the
provided ones. Packages and the Python version can be set independently.
py_require() is primarily called for its side effect of modifying
the manifest of "Python requirements" for the current R session that
reticulate maintains internally. py_require() usually returns NULL
invisibly. If py_require() is called with no arguments, it returns the
current manifest–a list with names packages, python_version, and
exclude_newer. The list also has a class attribute, to provide a print
method.
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.
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").
The packages argument also supports declaring a dependency from a Git
repository or a local file. Below are some examples of valid packages
strings:
Install Ruff from a specific Git tag:
Install Ruff from a specific Git commit:
Install Ruff from a specific Git branch:
Install MarkItDown from the main branch—find the package in the
subdirectory 'packages/markitdown':
Install MarkItDown from the local filesystem by providing an absolute path
to a directory containing a pyproject.toml or setup.py file:
reticulate caches ephemeral environments in the directory returned by
tools::R_user_dir("reticulate", "cache"). To clear the cache, delete the
directory:
unlink(tools::R_user_dir("reticulate", "cache"), recursive = TRUE)