Main Content

pyenv

Change default environment of Python interpreter

Since R2019b

collapse all in page

Syntax

pyenv
pyenv(Name,Value)
pe = pyenv(___)

Description

Use pyenv to change the default version or execution mode of the Python® interpreter. These changes are persistent across different MATLAB® sessions.

MATLAB selects and loads a Python interpreter when you type a Python expression from MATLAB using the py namespace, for example, py.list. To change the interpreter:

  • If Python is loaded in InProcess ExecutionMode, then restart MATLAB and run pyenv with the new version information.

  • If Python is loaded in OutOfProcess mode, then call terminate and run pyenv with the new version information.

MATLAB accesses these settings when loading the Python interpreter:

  • User settings for the Python environment, configured using the pyenv function. If the version you specify conflicts with the version specified by PYTHONHOME, then delete the environment variable before calling pyenv. The value set by pyenv is persistent across MATLAB sessions. For more information, see Set Python Version on Windows Platform or Set Python Version on Mac and Linux Platforms.

  • PYTHONHOME environment variable, specifies where to find the standard Python libraries if the value of pyenv.Status is NotLoaded. To view the value of the variable in MATLAB, type getenv("PYTHONHOME"). For more information, see Use PYTHONHOME Environment Variable.

  • System PATH environment variable. To view the system path in MATLAB, type getenv("PATH").

  • Windows® registry.

example

pyenv displays details about the current (default) Python environment.

example

pyenv(Name,Value) specifies parameters for setting the Python environment. For example, pyenv(Version="3.10") changes the default Python version on Microsoft® Windows platforms to 3.10.

pe = pyenv(___) additionally returns environment details as a PythonEnvironment object. Use this syntax with any of the arguments in previous syntaxes.

Examples

collapse all

pe = pyenv;
pe.Version
ans = 

    "3.10"

Set the execution mode to OutOfProcess.

pyenv(ExecutionMode="OutOfProcess")
ans = 

  PythonEnvironment with properties:

          Version: "3.10"
       Executable: "C:\Python310\pythonw.exe"
          Library: "C:\Python310\python310.dll"
             Home: "C:\Python310"
           Status: NotLoaded
    ExecutionMode: OutOfProcess

Create the variable.

py.list({"Monday","Tuesday","Wednesday","Thursday","Friday"});

Show the process. MATLAB displays information specific to your environment.

pyenv
ans = 

  PythonEnvironment with properties:

          Version: "3.10"
       Executable: "C:\Python310\pythonw.exe"
          Library: "C:\Python310\python310.dll"
             Home: "C:\Python310"
           Status: Loaded
    ExecutionMode: OutOfProcess
        ProcessID: "9768"
      ProcessName: "MATLABPyHost"

pe = pyenv;
if pe.Status == "Loaded" && pe.Version ~= "3.10"
    disp('To change the Python version, restart MATLAB, then call pyenv(Version="3.10").')
else
    pyenv(Version="3.10");
end

To verify if Python is installed on your system, check the PythonEnvironment Version property.

pe = pyenv;
if pe.Version == ""
    disp "Python not installed"
end

Input Arguments

collapse all

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: pe = pyenv(Version="/usr/bin/python",ExecutionMode="OutOfProcess")

Python version number (Windows platforms only) or executable file name, specified as a string or a character vector. For information about supported versions, see Configure Your System to Use Python.

  • If Version specifies a number, then the value must contain the major and minor version numbers separated by a period. The function looks for the version in the Windows registry. If you download the Python application from www.python.org/downloads, then the installation automatically adds the version to the registry. If you download the application from a different source, you must either add the version to the registry or call pyenv with the executable file name to change the version.

  • If Version is the name of an existing executable Python file, then the value must contain the name of the file and the full or relative path to the file. You can use this syntax on any platform or for repackaged CPython implementation downloads.

Example: pyenv(Version="3.10")

Example: pyenv(Version="/usr/bin/python")

Data Types: char | string

Execution mode indicating whether to run Python scripts in the same process as MATLAB, specified as 'InProcess' or 'OutOfProcess'. The default 'InProcess' runs the scripts in the MATLAB process. Use this mode for performance-critical use cases.

'OutOfProcess' starts a separate process and is used for safe execution of Python scripts and libraries. Select 'OutOfProcess' for:

  • Working with Python libraries which require a different version of a 3rd party library also required by MATLAB.

  • Debugging workflows.

When you call a Python function out-of-process, there is overhead associated with the call. This behavior might affect performance.

Data Types: char | string

Version History

Introduced in R2019b

See Also

Topics