Calling Python from MATLAB

MATLAB offers four routes into Python from the MATLAB side, and one route in the other direction.

The documentation sums the first two routes up this way: with the py. prefix MATLAB imports the entire module and can use all functions and classes of the Python code, while with pyrun and pyrunfile you must explicitly return Python objects to MATLAB using the outvars argument if you want to access Python data. Prefer the py. prefix for library calls and modules you write, and pyrun for a quick statement or a short script that needs MATLAB values as inputs.

Source: MATLAB documentation: Directly Call Python Functionality from MATLAB

Python can run in two places, and the choice is made with pyenv(ExecutionMode=...) before the interpreter is first used. The figure shows the difference.

Develop unstable Python code in OutOfProcess mode, so that a segmentation fault in an extension module or a runaway loop does not cost you your MATLAB session, and switch to InProcess for production use. The same trade-off exists in other languages that host Python: see "The same idea in other languages" below.

Source: MATLAB documentation: Out-of-Process Execution of Python Functionality

MATLAB needs a CPython installation of a version it supports; Python 2 support ended with R2022b (R2023a is the first release that lists only Python 3). The table is copied in structure from the "Versions of Python Compatible with MATLAB Products by Release" page, which MathWorks keeps current; check it before upgrading either product.

A correction to common summaries. It is easy to read that "Python 3.14 was added and 3.9 dropped in R2026a". The compatibility page and the release notes put both changes in R2026b; R2026a added 3.13. The R2026b release notes list "Python version 3.9 is no longer supported" among the changes marked as errors, so code that pins pyenv(Version="3.9") must move to a newer interpreter when you upgrade MATLAB.

Platform requirements from the installation page:

Source: MATLAB documentation: Install and Configure Python for Use in MATLAB

Source: MathWorks: Versions of Python Compatible with MATLAB Products by Release

There are three ways to get a supported Python: use one you already have, install it from python.org, or (since R2026b) install the "MATLAB Support for Python" add-on from the Add-Ons panel, which MathWorks provides for a version compatible with the release (3.13 for R2026b). Then you tell MATLAB which one to use, in one of three ways:

Prefer a virtual environment (an isolated folder of Python packages for one project) over the system interpreter, and point pyenv at the python executable inside it. The Python side of virtual environments, pip and requirements.txt is described in Virtual Environments and Packaging; the documentation also offers the MATLAB route through the External Languages panel, which uses the Python venv module and pip.

Source: MATLAB documentation: Install and Configure Python for Use in MATLAB

pyenv has three call forms:

The two name-value arguments are Version (a version number such as 3.13 on Windows, or the full path of an executable on any platform) and ExecutionMode (InProcess, the default, or OutOfProcess). The returned PythonEnvironment object has read-only properties, and the documentation shows this display for a freshly selected, not yet loaded interpreter:

(That text is the documented example, not output captured here.) Status is NotLoaded until the first Python call, then Loaded; after terminate it is Terminated. In out-of-process mode two more properties appear, ProcessID and ProcessName (MATLABPyHost). An empty Version means no usable Python was found.

The rules for changing the environment follow from the fact that an interpreter cannot be swapped under running code:

Source: MATLAB documentation: pyenv

Source: MATLAB documentation: terminate (PythonEnvironment)

The older function pyversion still exists but is documented as "not recommended"; use pyenv.

Since R2026a, the Python view of the External Languages panel does what scripts of pyenv calls did before. Open it with the "Open more panels" button of any sidebar, choose External Languages, and pick Python at the upper left. In the panel you can:

The documentation warns that installing or removing libraries with the panel runs pip against the environment itself, so it affects every other program on the machine that uses it, not only MATLAB. Scripts and CI jobs cannot click a panel; they use pyenv and the paths of a project-owned virtual environment instead.

Source: MATLAB documentation: Manage Python Environments Using External Languages Panel

Anything in the Python standard library or in an installed module is reachable by prefixing its name with py.. You do not import modules first.

Source: MATLAB documentation: Access Python Modules from MATLAB

Things that are different from both MATLAB and Python:

Source: MATLAB documentation: Access Elements in Python Container Types

MATLAB converts arguments automatically when it can and returns Python objects when it cannot. The rule is simple to state and has important exceptions: arguments are converted on the way in, results are mostly left as Python objects and you convert them on the way out. The tables below follow the R2026b page "Pass Data Between MATLAB and Python from MATLAB".

The heatflow plate keeps its temperature in a matrix T of size ny-by-nx (see Matrices and Arrays). A Python module that analyses a field with NumPy shows the whole round trip: a double matrix goes in as a numpy.ndarray, a dict and arrays come out. The Python file is:

Save it as heatflow_field.py next to the MATLAB script. The MATLAB script builds the same small plate as the indexing page (a hot top edge and a warm row below it), makes the module importable, calls the three functions and converts the results:

The MATLAB script was not run here. The Python module was run on the same field outside MATLAB, and the reference computation was run in Octave 11.3.0 with the shifted-block form of the stencil. Python output (Python 3.9.6, NumPy 2.0.2; the dict is the value summarize returns, with the zero-based row and col):

Octave 11.3.0 output of the reference computation (MATLAB uses the same formulas and prints the same numbers, possibly with a different layout):

Read the two together. The field has shape (5, 6) in both worlds, so a MATLAB ny-by-nx matrix and its NumPy array have the same shape and no transposition is needed; the interior Laplacian has shape (3, 4); the mean and the new second row agree. What does differ is the index base: Python reports the peak at row 0, column 0, MATLAB at (1,1), hence the + 1. The other difference is tie-breaking by memory order: argmax on a NumPy array scans in row-major order and MATLAB’s max(T(:)) scans down the columns first, so for a field with several equal maxima the two return different positions. In this field both find the corner first; a field whose maximum value appears at row 1, column 3 and at row 2, column 1 would give (1,3) in NumPy and (2,1) in MATLAB.

The sequence of conversions is drawn below.

Source: MATLAB documentation: Pass Data Between MATLAB and Python from MATLAB

pyrun and pyrunfile execute Python source rather than calling a named function. The syntax lines are:

code is a string scalar or character vector for one statement, or a string array, character array or cell array of character vectors for several lines (MATLAB inserts newline characters), or a Python code object made with the built-in compile. outputs names the Python variables to return, as a string array; with several outputs write [a,b] = pyrun(...). pyName=pyValue passes MATLAB data into the Python namespace under the given name. The key difference between the two: variables created by pyrun persist between calls in the Python namespace, whereas variables created by pyrunfile do not.

Using the temperature field T of the previous section:

and with a script file fieldstats.py, which finds the peak value and the number of rows of the field T that MATLAB provides:

Executing the same statements in plain Python with the same array gave a mean of 22.666666666666668, a peak of 100.0 and 5 rows (Python output, Python 3.9.6, NumPy 2.0.2), which is what the MATLAB calls return before conversion. A pyrunfile script can also receive command-line arguments, pyrunfile("greeting.py 'hello world'"), which the script reads from sys.argv as strings.

Limitations the documentation states for both functions:

The Run Python Code task (Live Editor, Task, Run Python Code; since R2024a) builds these calls for you in a live script, with the same persistence rules as pyrun.

Source: MATLAB documentation: pyrun

Source: MATLAB documentation: pyrunfile

Source: MATLAB documentation: Run Python Code

When Python raises an exception, MATLAB catches it and throws a matlab.exception.PyException (a class available since R2014b), which derives from MException. Its message has the form Python Error: Python class: message, and the property ExceptionObject holds the result of Python’s sys.exc_info, a tuple of exception type, value and traceback. You catch it with the ordinary try/catch of Errors, Warnings and Exceptions:

The Python module raises a ValueError for that call. Run in plain Python the message of that exception is (Python output, Python 3.9.6):

MATLAB prefixes it with Python Error: and the Python class, so the text you see in the Command Window is expected to read Python Error: ValueError: dt=1 exceeds the stability limit 0.208333 (the exact wording can vary by release; the page was not run in MATLAB). Test the class of the exception with isa(ME,"matlab.exception.PyException") rather than the identifier: the identifier is commonly reported as MATLAB:Python:PyException, but the pages used for this page do not state it, so confirm it with ME.identifier in your release if your code depends on it. The documentation draws a line between three kinds of failure:

On the Python side, the equivalent exceptions are described in Python Exceptions. The troubleshooting page of the documentation also links a MathWorks Support answer on debugging Python code called from MATLAB with Visual Studio Code, which this page does not reproduce.

Source: MATLAB documentation: Handle Python Exceptions

Source: MATLAB documentation: matlab.exception.PyException

Source: MATLAB documentation: Determine If Error Is Python or MATLAB Error

While you develop a Python module you change it and expect the next call to use the new code. MATLAB imports a module once per session, so by default the second py.newmod.myfunc still runs the first version. How to reload depends on the execution mode.

In-process interpreter, calls through the py. prefix. The documented recipe uses clear classes, then imports the module with importlib and reloads it:

The documentation adds that you should call clear classes from the command prompt (the base workspace), because inside a function workspace it may not clear all variables. It applies only to code called with the py. prefix. Code run with pyrun needs an out-of-process interpreter to be reloaded.

Out-of-process interpreter. Terminate the process and start a new one, possibly with different version settings, without restarting MATLAB:

In out-of-process mode clear classes is a heavier tool: it terminates the MATLABPyHost process and clears every Python object. For an in-process interpreter there is no way to unload the interpreter itself; restart MATLAB. The pattern is the same as in any language with a long-lived interpreter, and for heavy iteration many developers run the Python tests in a plain Python process (see Testing) and use MATLAB only for the integration.

Source: MATLAB documentation: Call User-Defined Python Module

Source: MATLAB documentation: Reload Out-of-Process Python Interpreter

The documentation lists what the Python interface does not support. The ones most likely to matter:

Source: MATLAB documentation: Limitations to Python Support

Treat the Python module as a unit that has its own tests (pytest, see Testing) and add a small MATLAB test that checks the integration: the conversion of a known matrix and the error class for an invalid call. In a class-based test, testCase.verifyEqual(double(py.heatflow_field.laplacian(T,dx)),expected,AbsTol=1e-9) compares the converted result, and testCase.verifyError(@() py.heatflow_field.explicit_step(T,a,dx,1),"MATLAB:Python:PyException") is the form to use only after you have confirmed the identifier in your release; otherwise catch the exception and test its class. See Unit Testing with matlab.unittest. On a continuous-integration machine nobody can open the External Languages panel, so call pyenv(Version=...) at the top of the job or set PYTHONHOME, and install the dependencies from requirements.txt first (see Continuous Integration). None of this was run here.

Hosting an interpreter in another program, converting values at the boundary, deciding whether the guest may crash the host, and handling exceptions across the boundary are problems every language faces. The Rust page Python Interop with PyO3 shows the mirror image of this page: instead of MATLAB calling Python, Rust code is called from Python (a native extension module built with maturin), or a Rust program embeds a Python interpreter. Its sections on mapping types and errors, the interpreter lock, and testing with pytest correspond to the sections here on type conversion, in-process and out-of-process execution, and exceptions. MATLAB’s in-process mode is the embedding case, and its out-of-process mode resembles running Python as a separate service. For the Python language itself, which the examples above assume you know, start at the Python section; the modules and packaging pages (Modules and Packages) explain the import path, and Numbers explains why Python distinguishes int and float. The C# page Native Interop covers the same boundary problem for managed code calling native code.

The two books consulted for this section predate the feature or ignore it: the primer was written for R2010a, long before py. existed (R2014b), and the 2021 mathematics volume does not cover external language interfaces. Web articles and blog posts of 2014 to 2018 describe a Python 2.7 interface, the pyversion function to select an interpreter (replaced by pyenv in R2019b, and now documented as not recommended), the vector-as-array.array conversion (the behaviour before R2025a), py.list conversions by hand where R2024a added dictionary(pydict) and table(pandas), and the need to restart MATLAB whenever a module changed (still true for in-process execution, but out-of-process mode and importlib.reload are the documented ways around it). Python 2 is no longer supported from R2023a. Tutorials that call urlread or write temporary CSV files to exchange data with Python describe workarounds from before the direct interface; the interface now exchanges arrays directly, and for text exchange formats see JSON, XML and Web Access. Finally, summaries that put Python 3.14 and the end of Python 3.9 in R2026a are off by one release: they are R2026b changes.