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


```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```


## Locating Python

It is not uncommon for several version of Python (and several conda or virtualenv environments within a given version) to be available on a given system. The **reticulate** package can bind to any of these versions, and in all cases will attempt to locate a version which includes the first Python package imported via the `import()` function. Consider the following code:

```{r}
library(reticulate)
scipy <- import("scipy")
scipy$amin(c(1,3,5,7))
```

In this case, the various versions of Python installed on the system will be scanned to see whether one of them includes the "scipy" Python package (the first version found that satisfies this requirement will be used).

By default, the version of Python found on the system `PATH` is checked first, and then some other conventional location for Py Python (e.g. `/usr/local/bin/python`, `/opt/local/bin/python`, etc.) are checked.

Note that for reticulate to bind to a version of Python it must be compiled with shared library support (i.e. with the `--enable-shared` flag).

## Providing Hints

There are two 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 directory containing 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")
```

The `use_condaenv` function will use whatever conda binary is found on the system 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 are by default considered only hints as to where to find Python (i.e. they don't produce errors if the specified version doesn't exist). You can add the `required` parameter to ensure that the specified version of Python is always used (it will be an error if the specified version doesn't exist):

```{r}
use_virtualenv("~/myenv", required = TRUE)
```

## Order of Discovery

The order in which versions of Python will be discovered and used is as follows:

1.  If specified, at the location referenced by the `RETICULATE_PYTHON` environment variable.

2.  If specified, at the locations referenced by calls to `use_python()`, `use_virtualenv()`, and `use_condaenv()`.

3. Within virtualenvs and conda envs that carry the same name as the first module imported. For example, if you execute `import("nltk")` then the following locations (among other similar ones) would be scanned for a version of Python with the **nltk** module installed:

    - $WORKON_HOME/nltk
    - ~/.virtualenvs/nltk
    - ~/anaconda/envs/nltk
    - ~/nltk

4.  At the location of the Python binary discovered on the system `PATH` (via the `Sys.which` function).

5.  At other customary locations for Python including `/usr/local/bin/python`, `/opt/local/bin/python`, etc.

The scanning for and binding to a version of Python typically occurs at the time of the first call to `import()` within an R session. As a result, priority will be given to versions of Python that include the module specified within the call to `import()` (i.e. versions that don't include it will be skipped).

## Python Packages

Each version of Python on your system has its own set of packages and as described above reticulate will automatically find a version of Python that contains the first package that you import from R. 

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()
```

