Python Version Configuration

Locating Python

It is not uncommon for several version of Python (and several conda or virtualenv environmetns 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:

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 a number of other conventional location for Py Python (e.g. /usr/local/bin/python, /opt/local/bin/python, etc.) are checked.

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 a 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:

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 paramter. For example:

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 actually exists:

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:

    • ~/nltk
    • ~/.virtualenvs/nltk
    • ~/anaconda/envs/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).

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:

py_config()

You can also use the py_discover_config() function to see what version of Python will be used without actually loading Python:

py_discover_config()