---
title: "Using Python with renv"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using Python with renv}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

If you're using `renv` with an R project that also depends on some Python
packages (say, through the [reticulate](https://rstudio.github.io/reticulate/)
package), then you may find `renv`'s Python integration useful.


## Activating Python Integration

Python integration can be activated on a project-by-project basis. Use
`renv::use_python()` to tell `renv` to create and use a project-local Python
environment with your project. If the `reticulate` package is installed and
active, then `renv` will use the same version of Python that `reticulate`
normally would when generating the virtual environment. Alternatively, you can
set the `RETICULATE_PYTHON` environment variable to instruct `renv` to use a
different version of Python.

If you'd rather tell `renv` to use an existing Python virtual environment, you
can do so by passing the path of that virtual environment instead -- use
`renv::use_python(python = "/path/to/python")` and `renv` will record and
use that Python interpreter with your project. This can also be used with
pre-existing virtual environments and Conda environments.


## Understanding Python Integration

Once Python integration is active, `renv` will attempt to manage the state of
your Python virtual environment when `snapshot()` / `restore()` is called. With
this, projects that use `renv` and Python can ensure that Python dependencies
are tracked in addition to R package dependencies. Note that future restores
will require both `renv.lock` (for R package dependencies) and
`requirements.txt` (for Python package dependencies).


### Virtual Environments

When using virtual environments, the following extensions are provided:

- `renv::snapshot()` calls `pip freeze > requirements.txt` to save the
  set of installed Python packages;

- `renv::restore()` calls `pip install -r requirements.txt` to install
  the previously-recorded set of Python packages.


### Conda Environments

When using Conda environments, the following extensions are provided:

- `renv::snapshot()` calls `conda env export > environment.yml` to save the
  set of installed Python packages;

- `renv::restore()` calls `conda env [create/update] --file environment.yml` to
  install the previously-recorded set of Python packages.

