Why is reticulate ignoring my managed Python requirements? A preflight check of the settings that steer Python selection, run before Python starts.
You call py_require(), and then import fails with ModuleNotFoundError. Often an old setting, such as RETICULATE_PYTHON or an activated virtualenv, makes reticulate use a different Python. retiaudit lists the visible selection hints and checks them against what you intend:
- Before Python starts. It does not load reticulate, run its discovery, start Python or run any file.
-
Against your intent. Say whether you want a managed environment (
py_require()) or an existing one, and it reports what conflicts. - Safe to share. Reports leave out environment values, local paths and file contents.
- Small. No dependencies; it reads only selected environment variables, package metadata and whether files exist.
Documentation: https://daikikumakura.github.io/retiaudit/
Installation
install.packages("retiaudit", repos = c(
"https://daikikumakura.r-universe.dev",
"https://cloud.r-project.org"
))Or from GitHub: remotes::install_github("DaikiKumakura/retiaudit"). Not on CRAN.
Quick start
library(retiaudit)
audit_python(intent = "managed") # you use py_require()
audit_python(intent = "existing", expected = "/path/to/python")| Function | What it does |
|---|---|
audit_python(intent) |
Collects the hints and returns a report with findings (code and severity) |
audit_markdown(report) |
Turns the report into Markdown to paste into an issue or a note |
The printed report has three parts: the environment hints (set or not), the project markers (present or not), and the findings.
Example: an old override blocks the managed environment
This synthetic example sets RETICULATE_PYTHON to a placeholder file; it does not run that file or start Python:
local({
previous <- Sys.getenv("RETICULATE_PYTHON", unset = NA_character_)
placeholder <- tempfile()
file.create(placeholder)
on.exit({
unlink(placeholder)
if (is.na(previous)) Sys.unsetenv("RETICULATE_PYTHON")
else Sys.setenv(RETICULATE_PYTHON = previous)
})
Sys.setenv(RETICULATE_PYTHON = placeholder)
report <- audit_python(intent = "managed")
report$findings[, c("code", "severity")]
})
#> code severity
#> 1 EXPLICIT_OVERRIDE_BLOCKS_MANAGED warningThe reproduced failure, diagnosis and remedy shows the whole case: the error, what retiaudit reports, and how to choose a managed or an existing environment deliberately.
What it checks
| Hint | Examples |
|---|---|
| Explicit overrides | interpreter path, named environment |
| Managed environments | enable and disable flags, with their precedence |
| Active environments | activated virtualenv, project-local virtualenv folders |
| Other markers | Poetry and Pipenv files, interpreter fallback, default r-reticulate environment |
| Consistency | missing interpreter files, disagreement with an expected path |
| Startup | presence of .Rprofile, .Renviron and renv.lock (contents are not read) |
The audit checks that a file exists, not that it is a working Python. It never changes settings or recommends deleting an environment: review the findings and decide in a fresh R session.
How it differs from reticulate’s diagnostics
| Tool | Purpose |
|---|---|
reticulate::py_config() |
Inspect the Python configuration; can initialize Python |
reticulate::py_discover_config() |
Discover a configuration without loading Python; discovery still runs |
retiaudit::audit_python() |
Check visible hints against your intent, without loading reticulate or running discovery |
retiaudit complements the official diagnostics; it does not reimplement reticulate’s discovery.
Share a report
report <- audit_python(intent = "managed")
cat(paste(audit_markdown(report), collapse = "\n"))
# writeLines(audit_markdown(report), "python-preflight.md")The report keeps fixed variable names, marker names, presence flags and the reticulate version, and leaves out environment values, local paths, startup-file contents, requirements and error traces. Review it before sharing.
Limits
- No network calls, subprocesses, environment changes, installation, file writes, startup-file execution or reticulate loading.
- It does not see
use_python()calls, a Python that is already loaded, delayed imports, global startup code, package availability or ABI compatibility. - Auditing another project folder does not simulate starting R there.
- No findings means no visible conflict, not a working Python setup.
- Written for reticulate 1.41 or later; older versions get a warning.
Background
The problem is described in reticulate’s selection guidance and managed requirements documentation; related reports include rstudio/reticulate#1809 and rstudio/reticulate#1832. retiaudit flags an renv lockfile but does not solve the integration of renv and managed environments.
Citation
Cite the archived version: https://doi.org/10.5281/zenodo.24210476.