matlab-call-python

从 MATLAB 调用 Python

使用现代 API、正确配置环境并进行结构化错误恢复，从 MATLAB 调用 Python 库。

适用场景

• 编写 MATLAB 代码，通过 py.*、pyrun 或 pyrunfile 调用 Python
• MATLAB 代码因 ModuleNotFoundError、Python is not configured 或其他 Python 相关错误而失败
• 用户要求为 MATLAB 配置 Python 或创建虚拟环境
• 用户要求安装供 MATLAB 使用的 Python 包

不适用场景

• 从 Python 调用 MATLAB（MATLAB Engine API for Python——调用方向不同）
• 构建 MEX 文件或 Python C 扩展
• 纯 Python 开发，未涉及 MATLAB
• MATLAB Compiler 或 MATLAB Production Server 部署

规则

绝不使用 pyargs

使用 MATLAB 的 name=value 语法传递 Python 关键字参数。pyargs 已过时（R2021a 起支持 name=value）。

% TEMPLATE — not executable (requires scikit-learn)
rfc = py.sklearn.ensemble.RandomForestClassifier(n_estimators=int32(100), random_state=int32(42));

绝不使用 pyversion

不建议使用 pyversion。请使用 pyenv，它支持 terminate、ExecutionMode 和环境切换。

始终使用 Bash 工具安装 pip 包和创建 venv

不要使用 MATLAB system()。Bash 工具可提供流式输出，并避免复杂的字符串转义。

始终先执行恢复流程，再安装任何 pip 包或创建 venv

在运行 pip install 或创建虚拟环境之前，必须先遵循 references/environment-setup.md。不要根据错误回溯推断 Python 路径——这些路径显示的是 importlib 内部信息，不是正确的安装目标。

调用 terminate(pyenv) 前始终先征求用户确认

terminate(pyenv) 会重启 Python 进程并清除所有 Python 状态（已导入的模块、变量和打开的连接）。调用 terminate 前，始终告知用户哪些内容会丢失，并征得明确同意。

Python 需要 int 时始终使用整数类型封装

MATLAB 默认传递 double。Python 函数需要 int 时却收到 float，会导致 TypeError。对计数、索引和大小参数使用 int32()。如果数值无法用 32 位表示，则使用 int64() 或 uint64() 以防溢出。

R2026a 或更高版本中，字符串数组始终使用 pystringarray

在 R2026a 或更高版本中向 Python 传递 MATLAB 字符串数组时，请使用 pystringarray。需要 NumPy 2.0 或更高版本。在 R2025b 及更早版本中，或 NumPy < 2.0 时，请使用 py.list(cellstr(...))。

% R2026a and later:
names = ["Alice", "Bob", "Charlie"];
pyNames = pystringarray(names);

% R2025b and earlier:
names = ["Alice", "Bob", "Charlie"];
pyNames = py.list(cellstr(names));

工作流

从 MATLAB 调用 Python 时，请遵循此工作流。

1. 使用现代语法编写 Python 代码

result = py.module.function(arg1, arg2, kwarg1="value", kwarg2=42);

优先使用 py.module.function(...) 直接调用函数——这种写法易读，可与 MATLAB 工作区集成，并支持代码补全。仅在多语句脚本中使用 pyrun，此类脚本的变量和导入内容会在多次调用间保留在 Python 内存中（类似 REPL 的执行方式）。仅在运行独立的 .py 文件时使用 pyrunfile（相当于从命令行运行；状态不会保留）。

2. 运行代码

通过 mcp__matlab__evaluate_matlab_code（用于内联代码）或 mcp__matlab__run_matlab_file（用于脚本文件）执行。

3. 如果成功——完成

4. 如果出现 Python 错误——进行分类排查

仅针对环境相关错误遵循 references/environment-setup.md：

1. ModuleNotFoundError
2. MATLAB 报错，指出无法解析 py.* 名称（例如，“Unable to resolve the name 'py.numpy'”）
3. pyenv().Executable 为空
4. py 或 pyenv 调用报错，指出环境不受支持
5. 其他任何表明缺少库或环境未配置的错误

对于其他所有 Python 错误（ValueError、TypeError、Python 代码本身的逻辑错误）——直接调试代码。这些是代码错误，而非环境问题。

主要功能

功能	用途	适用版本
pyenv	查询/配置 Python 环境	R2019b
pyrun	执行 Python 语句；变量会在多次调用之间保留	R2021b
pyrunfile	执行独立的 .py 文件	R2021b
pystringarray	将 MATLAB 字符串数组传递给 Python	R2026a

InProcess 与 OutOfProcess

• OutOfProcess：在单独的进程中启动 Python。可缓解 MATLAB 与 Python 之间的第三方库冲突，因此可无冲突地使用大多数 Python 包。terminate(pyenv) 会重启 Python，而无需重启 MATLAB。可以自由切换环境。
• InProcess：（默认）在同一个 MATLAB 进程中启动 Python。为获得更好的性能，优先选择此模式。无法终止。如果已在 InProcess 模式下加载 Python，用户必须完全重启 MATLAB 才能更改 Python 配置。

在 ExecutionMode="OutOfProcess" 模式下，如果正在使用自定义 Python 模块，并且加载模块后需要进行更改，或在会话中途安装了包，则在再次调用该模块前，务必调用 terminate(pyenv)。

在 ExecutionMode="InProcess" 模式下，如果正在使用自定义 Python 模块，并且加载模块后需要进行更改，则务必运行以下命令重新加载模块：

clear all;
clear classes;
mod = py.importlib.import_module("<module_name>");
py.importlib.reload(mod);

常用模式

使用关键字参数调用 Python 函数

rfc = py.sklearn.ensemble.RandomForestClassifier(n_estimators=int32(100), random_state=int32(42));
rfc.fit(XTrain, yTrain);
predictions = double(rfc.predict(XTest));

配置 MATLAB 使用虚拟环境

使用 Bash 工具创建虚拟环境（venv）后，将 MATLAB 指向该环境：

% Terminate current Python if loaded
terminate(pyenv);

% Point at venv executable
pyenv(Version="/path/to/.venv/Scripts/python.exe");

% Verify
disp(pyenv().Executable);
py.numpy.array([1, 2, 3]);

约定

• 当关键字参数名称与 MATLAB 变量冲突时，追加 Val（例如，使用 py.complex(imag=imagVal)，而不是 py.complex(imag=imag)）
• 避免“激活”虚拟环境——MATLAB 不使用激活脚本。直接将 pyenv(Version=...) 指向虚拟环境的可执行文件。

---

版权所有 2026 The MathWorks, Inc.

---