1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
---
title: "Python Version Configuration"
output:
rmarkdown::html_vignette
editor_options:
markdown:
wrap: 80
vignette: >
%\VignetteIndexEntry{Python Version Configuration}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
::: {.alert .alert-info}
> ## **⚠ Updated Guidance**
>
> This vignette provides guidance for how to help reticulate discover and use
> self-managed Python installations. This is generally no longer necessary nor
> recommended beginning with Reticulate version 1.41.
>
> We now recommend using `py_require()` to declare Python dependencies and
> leting reticulate automatically resolve dependencies.
>
> If you are attempting to use `py_require()` but reticulate is not resolving
> the correct environment, Consult the [Order Of Discovery](#order-of-discovery)
> section below and ensure no Python installations higher in the order of
> discovery are present.
>
> For example, if the `r-reticulate` virtualenv is being discovered in favor of
> `py_require()`'s ephemeral env, you can remove it:
>
> ``` r
> virtualenv_remove("r-reticulate")
> ```
>
> For more details, see the `py_require()` docs and the [Installing Python
> Packages](python_packages.html) vignette.
:::
## Locating Python
It is not uncommon for several installations of Python to be available on a
given system. The **reticulate** package can bind to almost any Python
installations, and provides a variety of convenient ways to allow the user to
implicitly or explicitly specify which Python installation to select.
Note that for reticulate to bind to a version of Python it must have been
compiled with shared library support (i.e. with the `--enable-shared` flag).
Consider the following code:
``` r
library(reticulate)
py_eval("1+1")
```
In this case, reticulate will search for a suitable Python installation. In the
absence of other hints (detailed below), reticulate will fallback to an
environment named "r-reticulate", creating it if necessary.
Consider another case:
``` r
library(reticulate)
scipy <- import("scipy")
scipy$amin(c(1,3,5,7))
```
In this case, reticulate will first look for an environment named "r-scipy", and
if that doesn't exist, it will fallback to the environment named "r-reticulate".
## Providing Hints
There are a few ways you can provide hints as to which version of Python should
be used:
1. By setting the value of the `RETICULATE_PYTHON` environment variable to a
Python binary. Note that if you set this environment variable, then the
specified version of Python will always be used (i.e. this is prescriptive
rather than advisory). To set the value of `RETICULATE_PYTHON`, insert
`Sys.setenv(RETICULATE_PYTHON = PATH)` into your project's .Rprofile, where
`PATH` is your preferred Python binary.
2. By calling one of the these functions:
| Function | Description |
|--------------------|-------------------------------------------------------|
| `use_python()` | Specify the path a specific Python binary. |
| `use_virtualenv()` | Specify the name of (or path to) a Python virtualenv. |
| `use_condaenv()` | Specify the name of a Conda environment. |
For example:
``` r
library(reticulate)
use_python("/usr/local/bin/python")
use_virtualenv("~/myenv")
use_condaenv("myenv")
```
If the `use_virtualenv()` function is supplied a name of a virtual environment
(as opposed to a path), it will look in the virtualenv root directory, by
default `~/.virtualenvs`, and configurable by setting the environment variable
`WORKON_HOME`.
The `use_condaenv()` function will use whatever conda binary is found on the
`PATH`. If you want to use a specific alternate version you can use the `conda`
parameter. For example:
``` r
use_condaenv(condaenv = "r-nlp", conda = "/opt/anaconda3/bin/conda")
```
Note that the `use_*()` functions take an optional `required` argument. By
default, a value of `required = NULL` is equivalent to `required = TRUE` in most
circumstances. If `required = FALSE` is supplied, then the call is considered an
optional hint as to where to find Python (i.e. it doesn't produce an error if
the specified version doesn't exist).
## Order of Discovery {#order-of-discovery}
The order in which Python installation will be discovered and used is as
follows:
1. If specified, the location referenced by the `RETICULATE_PYTHON` environment
variable. (Path to a Python binary)
2. If specified, the location referenced by the `RETICULATE_PYTHON_ENV`
environment variable. (Path to or name of a virtual environment or conda
environment)
3. If specified, the location referenced by calls to `use_python()`,
`use_virtualenv()`, and `use_condaenv()` with `required = TRUE` (the
default).
4. If the environment variable `RETICULATE_USE_MANAGED_VENV="yes"` is set, then
reticulate will use an ephemeral virtual environment that satisfies all the
requirements declared via `py_require()`
5. If the environment variable `VIRTUAL_ENV` is defined (typically from running
an `activate` script before R started, or from having the "Automatically
activate project-local Python environments" option enabled in the RStudio
IDE), then the Python from the activated environment is used.
6. If the current working directory contains a pyproject.toml file from a
poetry environment, the Python installation from the poetry environment is
used.
7. If the current working directory contains a Pipfile associated with a
pipenv, the Python installation from pipenv is used.
8. If the current working directory contains a directory named "venv",
"virtualenv", ".venv", or ".virtualenv", and that directory is a Python
virtual environment, the Python from the virtual environment is used.
9. If there was a call (typically from within a package using reticulate), of
the form: `import("bar", delay_load = list(environment = "r-barlyr")`, and
there exists a virtual environment or conda environment named `"r-barlyr"`,
it is used.
10. If any call to `use_python()`, `use_virtualenv()`, or `use_condaenv()` was
made with `required = FALSE`, or from within a packages `.onLoad()`
function, and the referenced python installation exists, it is used.
11. If there was a call to `import("bar")`, and there exists a virtual
environment or conda environment named `"r-bar"`, it is used.
12. If specified, the location referenced by the `RETICULATE_PYTHON_FALLBACK`
environment variable. (Path to a python binary)
13. If a virtual environment named `"r-reticulate"` exists, it is used.
14. In the absence of any expression of preference via one of the ways outlined
above, reticulate falls back to resolving an ephemeral virtual environment
that satisfies all the requirement declared via `py_require()`. To disable
this feature, you can set env var `RETICULATE_USE_MANAGED_VENV="no"`
15. If none of the above Python installations can be used, then we fall back to
using the Python on the `PATH`, or on Windows, the Python referenced by the
registry. If both `python` and `python3` are on the `PATH`, then reticulate
will prefer `python3`, unless only `python` has NumPy installed, or
`python3` is built for a different architecture than R (e.g., x86).
## Python Packages
You can learn more about installing Python packages into virtualenvs or Conda
environments in the article on [Installing Python
Packages](python_packages.html).
## Configuration Info
You can use the `py_config()` function to query for information about the
specific version of Python in use as well as a list of other Python versions
discovered on the system:
``` r
py_config()
```
You can also use the `py_discover_config()` function to see what version of
Python will be used without actually loading Python:
``` r
py_discover_config()
```
|
