📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / matlab / references / python-integration.md

MATLAB and Python Integration

MATLAB and Python Integration

This reference is pinned to MATLAB R2026a as reviewed on 2026-07-23. Calling Python from MATLAB and calling MATLAB from Python are different interfaces with different process, data, and license behavior.

Exact R2026a compatibility

MathWorks' support table lists 64-bit CPython 3.9, 3.10, 3.11, 3.12, and 3.13 for:

MATLAB Interface to Python;
MATLAB Engine for Python;
MATLAB Compiler SDK for Python;
MATLAB Production Server Client Library.

The current MathWorks-maintained PyPI release reviewed here is matlabengine==26.1.12, released 2026-05-08. It requires MATLAB R2026a. Do not install a floating latest package for a reproducible environment.

uv pip install "matlabengine==26.1.12"

Installation does not include MATLAB or grant a license. Engine requires an installed R2026a on the same machine; MATLAB Runtime alone is insufficient. The Python architecture must match MATLAB.

R2026a also ships a preinstalled Engine distribution at the single named path:

<matlabroot>/extern/engines/python/dist

Add only that confirmed path to the selected environment when using this method. Do not print or upload the full PATH, PYTHONPATH, environment, license configuration, home directory, or credentials.

Plan compatibility without execution

python scripts/plan_python_compatibility.py \
  --matlab-release R2026a \
  --python-version 3.13 \
  --engine-version 26.1.12

The planner uses a bundled dated support table. It does not import matlab.engine, inspect the environment, locate installations, start MATLAB, or check out a license. --include-launch-snippet adds an explicitly labeled launch example to the JSON plan but still does not execute it.

Calling Python from MATLAB

Review and pin one interpreter before any py.* access:

environment = pyenv( ...
    Version="/reviewed/venv/bin/python", ...
    ExecutionMode="OutOfProcess");

On Windows, a registered version can be selected by version, but a full named executable is clearer. On macOS/Linux, use the full executable. The Python build architecture must match MATLAB. MATLAB does not support CPython from the Microsoft Store.

Interpreter switching:

in-process: restart MATLAB before changing the loaded interpreter;
out-of-process: terminate(pyenv) can stop the external interpreter, after which pyenv can be reconfigured.

Out-of-process isolates interpreter crashes and allows reload, but it is not a security sandbox. Data plus transfer metadata are limited to 2 GiB per out-of-process transfer. Python modules can perform arbitrary process, file, network, native, and credential operations.

Never run untrusted py.*, pyrun, pyrunfile, Python modules, wheels, or requirements files. pyrun and pyrunfile are dynamic code execution surfaces.

Calling MATLAB from Python

Starting Engine is explicit execution:

import matlab.engine

engine = matlab.engine.start_matlab()
try:
    result = engine.sqrt(16.0)
finally:
    engine.quit()

start_matlab() creates a MATLAB process, can execute startup code, and can check out a MATLAB license. Never call it merely to probe availability. Review startup paths/actions and confirm entitlement first.

connect_matlab() connects to a deliberately shared local MATLAB session; find_matlab() lists shared sessions. Sharing changes the trust boundary and must be explicitly approved. Do not connect to an unknown session.

Only add narrow reviewed paths:

engine.addpath("/reviewed/project/src", nargout=0)
value = engine.analyzeSignal(
    matlab.double([[1.0], [2.0], [3.0]]),
    nargout=1,
)

Do not use recursive path additions. Pass fixed function names, not text to eval, and set nargout deliberately. Redirect output to bounded io.StringIO only when needed; logs can contain paths or data.

MATLAB-to-Python conversion in R2026a

Scalar automatic mappings include:

MATLAB	Python
real `double`/`single`	`float` by default; type hints can select `int`
complex float	`complex`
integer scalar	`int`
logical scalar	`bool`
string scalar/character vector	`str`
missing string	`None`-like string conversion documented by MathWorks
`dictionary`/scalar `struct`	`dict`
`table`/`timetable`	pandas `DataFrame`
`datetime`	`datetime.datetime`
`duration`	`datetime.timedelta`

With NumPy available, numeric/logical MATLAB arrays convert to NumPy arrays with corresponding precision/sign/complex dtype. Without NumPy, numeric arrays use Python buffer/memoryview behavior. Since R2025a, array conversion behavior changed; test code migrated from older vector array.array assumptions.

R2026a additions:

MATLAB string vectors automatically convert to Python lists;
pystringarray converts MATLAB string arrays to NumPy StringDType arrays;
missing string entries need explicit round-trip tests.

No automatic conversion is documented for multidimensional character/cell arrays or M-by-N string arrays where both dimensions exceed one. Sparse arrays, nonscalar structure arrays, categorical arrays, containers.Map, MATLAB objects, and metadata classes are unsupported in the MATLAB-to-Python interface.

Python-to-MATLAB conversion

MATLAB automatically converts selected scalar Python returns. Other values use explicit conversion:

Python value	MATLAB conversion
`py.str`	`string` or `char`
Python numeric scalar	`double`, `single`, or integer constructors
`py.bytes`	`uint8`
`py.numpy.ndarray`	matching MATLAB numeric class or `string` where supported
`py.list`/`py.tuple`	numeric/logical/string/cell conversion when homogeneous/compatible
mapping protocol / `py.dict`	`dictionary` or `struct`
pandas `DataFrame`	`table`/`timetable` with documented conversion
Python datetime/timedelta/NumPy time	MATLAB `datetime`/`duration` conversions

Always test:

rank and row/column orientation;
C-order versus column-major interpretation;
dtype width/sign and complex values;
NaN, Inf, None, NaT, missing strings, and categorical values;
table index versus timetable row times;
time zones and units;
dictionary key restrictions and column-name normalization;
copies versus shared/buffer-backed memory.

Do not flatten an array to "fix" a shape mismatch without recording the ordering contract.

MATLAB Engine array classes

The matlab Python package provides MATLAB array classes such as matlab.double, matlab.single, signed/unsigned integer classes, and matlab.logical. These are for Engine calls, not general NumPy replacements.

column = matlab.double([[1.0], [2.0], [3.0]])
matrix = matlab.double([[1.0, 2.0], [3.0, 4.0]])

Construct the intended dimensions explicitly. Function outputs can be Engine proxy/object types; convert only through documented APIs.

Serialization and exchange

MATLAB does not support saving Python objects into MAT files.
Never use Python pickle for MATLAB exchange. Pickle deserialization executes attacker-controlled behavior.
For simple data, prefer schema-documented CSV/JSON/Parquet/HDF5.
For trusted MATLAB arrays, use MAT with explicit version and inventory it before loading in another process.
SciPy loadmat is not used by this skill's inventory. It can deserialize complex structures and is not a safety scanner.

Compiler SDK distinction

MATLAB Compiler SDK for Python packages are not MATLAB Engine:

building requires MATLAB, MATLAB Compiler SDK, and source dependencies;
deployed components use a compatible MATLAB Runtime under applicable terms;
generated Python packages are not supported as Python modules called back from MATLAB's Python interface;
Engine itself requires full installed MATLAB, not Runtime.

Confirm product, target release, platform, package, runtime, and license terms.

Troubleshooting without broad disclosure

Collect only named facts:

MATLAB release/update and architecture;
one Python executable path and major.minor;
Engine package version;
selected pyenv status/mode (not all environment values);
one failing function, input classes/shapes, and redacted traceback;
whether NumPy/pandas are required and their pinned versions.

Do not ask for env, set, complete PATH, complete sys.path, license files, tokens, home-directory listings, or credentials.