Using Python inside targets

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

This vignette is the reference for running Python scripts as targets steps with reticulate: every tar_target_py() argument, how to choose the Python environment, and the common use cases. For a gentler tour start with vignette("get_started"); for Julia see vignette("julia").

The two constructors

tar_target_py(): bare name (and unquoted pattern), for direct use in _targets.R.
tar_target_py_raw(): string name, for use inside targets factories.

Both return a single targets target and forward every targets::tar_target_raw() argument, so anything an ordinary target supports (pattern, format, iteration, deployment, resources, cue, memory, error, priority, description, …) works exactly as usual.

Arguments

Scripts

Argument	Meaning
`script`	Path to the Python script to run (required).
`pre_script`	Optional R script run before the Python script. Assign a named list `to_py` to push objects into Python’s `__main__`.
`post_script`	Optional R script run after the Python script. `py` and `py_get()` are available; its last expression is the value (object mode) or file paths (file mode).

Each of the three accepts either a literal path string (untracked: editing the file does not invalidate the target) or a tar_target_path("name") reference to an upstream format = "file" target (tracked: the step re-runs when the file changes). See “Tracking scripts” below.

Wiring in data and reading it back

Argument	Meaning
`inputs`	Named character vector mapping the name seen in the step to an upstream target, e.g. `c(x = "prepared_x")`. Each becomes a real dependency (and is sliced under dynamic branching).
`output`	`"object"` (default) returns a converted R object; `"file"` returns a character vector of paths and defaults `format` to `"file"`.
`retrieve`	Character vector of Python variable names to return when there is no post-script (object mode). One name returns that object; several return a named list.
`files`	Character vector of paths to return when there is no post-script (file mode).

Choosing the interpreter / environment

Argument	Meaning
`python`	Path to a specific interpreter executable.
`env` + `env_manager`	Point at an existing environment built by a known tool.
`python_version`	A version string (e.g. `"3.12"`); reticulate provisions it via an ephemeral uv environment.

These are alternatives: normally set only one. If several are given, the first in this precedence wins: python > env/env_manager > python_version > nothing. They are covered in detail in the next section.

The three-script model

 upstream targets ─► pre_script (R) ─► script (.py) ─► post_script (R) ─► target value
                     builds `to_py`     computes         reads `py$name` /
                                        `result`         `py_get("name")`

script: the Python file. Runs in the __main__ module.
pre_script: the inputs are already bound by name. Assign a named list to_py; each element is pushed as a top-level variable into __main__ using reticulate’s conversion rules.
post_script: py (the reticulate __main__ proxy) and py_get(name) (an explicit reticulate::py_to_r() shortcut) are available. Read a variable with py$result or py_get("result").

Object output

py/compute.py:

# `x` was pushed from R by the pre-script.
seq = list(x) if hasattr(x, "__iter__") else [x]
result = {"sum": float(sum(seq)), "n": len(seq), "mean": float(sum(seq)) / len(seq)}

R/pre_push.R:

to_py <- list(x = x)   # `x` came from inputs = c(x = "prepared_x")

R/post_result.R (last expression becomes the value):

res <- py_get("result")
data.frame(sum = res$sum, n = res$n, mean = res$mean)

_targets.R:

list(
  tar_target(prepared_x, c(1, 2, 3, 4)),

  # (a) return a Python variable directly with `retrieve` (no post-script)
  tar_target_py(
    name = py_direct,
    script = "py/compute.py",
    inputs = c(x = "prepared_x"),
    pre_script = "R/pre_push.R",
    retrieve = "result"
  ),

  # (b) reshape the result in a post-script
  tar_target_py(
    name = py_prepost,
    script = "py/compute.py",
    inputs = c(x = "prepared_x"),
    pre_script = "R/pre_push.R",
    post_script = "R/post_result.R"
  )
)

File output

Set output = "file" when the script writes to disk; return the path(s) from the post-script (or via files when there is no post-script). The target format becomes "file" automatically.

tar_target_py(
  name = py_file,
  script = "py/write_csv.py",       # writes a CSV, stores its path in `out_path`
  inputs = c(x = "prepared_x"),
  pre_script = "R/pre_push.R",
  post_script = "R/post_files.R",   # returns py_get("out_path")
  output = "file"
)

Dynamic branching

inputs are real dependencies, so pattern branches them:

list(
  tar_target(chunks, list(10, 20, 30)),
  tar_target_py(
    name = py_branch,
    script = "py/compute.py",
    inputs = c(x = "chunks"),
    pre_script = "R/pre_push.R",
    retrieve = "result",
    pattern = map(chunks)           # 3 branches: x = 10, 20, 30
  )
)

Run the branches in parallel by setting a crew controller (see vignette("get_started"), the “Parallelism and isolation with crew” section).

Choosing the Python environment

The four selection arguments and when to reach for each:

python: a path to a specific interpreter executable (e.g. ".venv/Scripts/python.exe"). Use when you already have the exact interpreter and want no ambiguity.
env + env_manager: an existing environment built by a known tool (env_manager says how to read env; see the table). Recommended for reproducible pipelines: install the packages once, every run reuses them.
python_version (e.g. "3.12"), not an environment, just an interpreter version: reticulate provisions it through an ephemeral, uv-managed environment (py_require()), resolving packages on the fly. Use when only the version matters.
nothing set: reticulate’s default discovery (the computer’s Python, or an ephemeral uv-managed one on recent reticulate). Fine for exploration; pin an environment for reproducibility.

The key contrast is reproducible vs throwaway: env/python reuse an environment you built and pinned; python_version lets reticulate build a fresh one keyed only on a version. One more difference: python and env/env_manager override an ambient RETICULATE_PYTHON (e.g. an RStudio project Python inherited by crew workers), while python_version and the default respect it.

`env_manager`	what `env` is	reticulate call
`"system"` (default)	none (optionally set `python`)	`use_python(python)` or default
`"venv"`	a `python -m venv` directory path	`use_virtualenv(env)`
`"virtualenv"`	same as venv	`use_virtualenv(env)`
`"conda"`	conda environment name	`use_condaenv(env)`
`"uv"`	a uv-created venv directory path	`use_virtualenv(env)`
`"poetry"`	a poetry project directory path	`poetry env info -p`, then `use_virtualenv()`

"virtualenv", "venv", and "uv" all point at a standard Python virtualenv and behave identically: this includes one created by renv::use_python() (use env_manager = "venv" with the path under renv/python/virtualenvs/). For these managers, a relative env that is an existing directory is expanded to an absolute path, so env = ".venv" works; a bare name that is not a directory is passed through unchanged, so a genuine named environment still resolves. Setting env while env_manager = "system" is an error.

Use case 1: global / system default

Set nothing; reticulate uses the computer’s default Python (on recent versions, an ephemeral uv-managed one provisioned on first use). Convenient for exploration; pin a real environment for reproducibility.

tar_target_py(
  name = probe,
  script = "py/probe.py",
  retrieve = "result"
  # no env / env_manager / python -> computer default Python
)

Use case 2: a pinned uv virtualenv (recommended)

Create it once, then point to it. Reproducible: the exact package set is reused every run.

uv venv .venv
uv pip install --python .venv/Scripts/python.exe numpy pandas scikit-learn

tar_target_py(
  name = fit,
  script = "py/fit.py",
  env_manager = "uv",
  env = ".venv",
  retrieve = "model"
)

Use case 3: a poetry project

Give the project directory (the folder with pyproject.toml); its virtualenv is resolved for you with poetry env info -p.

tar_target_py(
  name = embed,
  script = "py/embed.py",
  env_manager = "poetry",
  env = "path/to/poetry_project",
  retrieve = "vectors"
)

If the poetry on PATH is not the one you want, select a specific executable with options(tarpolyglot.poetry = "/path/to/poetry").

Use case 4: a plain venv or a conda env

# python -m venv .venv
tar_target_py(
  name = score,
  script = "py/score.py",
  env_manager = "venv",
  env = ".venv",
  retrieve = "result"
)

# a named conda environment
tar_target_py(
  name = classify,
  script = "py/classify.py",
  env_manager = "conda",
  env = "my_conda_env",
  retrieve = "labels"
)

Use case 5: pin just the version

To fix the interpreter version without naming an environment, use python_version (leaves the environment at the default, uv-managed one):

tar_target_py(
  name = probe_ver,
  script = "py/probe.py",
  python_version = "3.12",           # reticulate provisions 3.12 via uv
  retrieve = "result"
)

One interpreter per session. reticulate binds a single Python per R session, so all Python targets that run in the same session share one environment. To use different environments in one pipeline, run those targets on separate crew workers (see vignette("get_started")).

Tracking scripts as dependencies

By default script / pre_script / post_script are untracked literal paths. To have the step re-run when a script changes, track it with a format = "file" target and reference it with tar_target_path():

list(
  tar_target(fit_py, "py/fit.py", format = "file"),

  tar_target_py(
    name = fit,
    script = tar_target_path("fit_py"),   # re-runs when py/fit.py changes
    pre_script = "R/pre_fit.R",           # still an untracked literal path
    inputs = c(x = "data"),
    retrieve = "model"
  )
)

Conversion caveats

A bare number in R is a double; use L (e.g. 42L) when Python needs an int.
Python is 0-indexed.
For anything that does not round-trip cleanly, use file mode.

See ?tar_target_py and ?run_py_step for the full argument reference.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.