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:

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:

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:

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

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 it’s 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.

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:

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