MATLAB® based Python® Requirements manager

MPyReq is a MATLAB-based Python requirements manager that simplifies installing and configuring Python environments for MATLAB projects.

MPyReq is a MATLAB-based Python requirements manager that simplifies installing and configuring Python environments for MATLAB projects. It handles Python version management, package installations, git repository cloning, and weight file downloads with a simple API. MPyReq ensures consistent Python environments across sessions by caching configurations and providing runtime setup for your Python dependencies.

Setup

To Run:

1. Download MPyReq.m
2. Ensure MPyReq.m is on the MATLAB path. Not just in pwd, but on MATLAB path.
3. Call MPyReq.setInstallFolder(largeSSDFolder) to set the install folder. This only needs to be done once per machine. All subsequent uses of MPyReq share downloaded content from this folder.

Getting Started

Invoke help to see documentation

help MPyReq.m

Note: Click 'Open in MATLAB Online' and run the demoCellpose example in MATLAB Online. Remember to follow step 2 & 3 above. You can set install folder to "/tmp/pydata" when trying it out.

Example

% Do this once per machine (saved in settings)
MPyReq.setInstallFolder("pathToLocalLargeSSDFolder")

% First ever run of this section     - Does installation and Runtime setup
% First run in a subsequent session  - Just Runtime Setup
% Second run in any session          - A very quick check to ensure env is up
MPyReq.python("3.12");
MPyReq.pipPackage("cellpose"); 


im = imread("AT3_1m4_01.tif");

% Use Python interface to call into Python code
% See: https://cellpose.readthedocs.io/en/latest/api.html
model = py.cellpose.models.CellposeModel(gpu=true);
outputs = model.eval(im);

labels = uint16(outputs{1});
imageshow(im,OverlayData=labels)

More Examples

Run the following examples after ensuring to set an installation folder using the call below. Ideally, this folder should be a fast access (e.g SSD) with ~15+ GB free space. These examples download large libraries and model files. These examples were tested on a glnxa64 machine with a working GPU.

demoCellpose - Run https://www.cellpose.org/ cell segmentation model.

demoStarDist - Run https://github.com/stardist/stardist object detection with star convex shapes (WIP, model loads, example needs better data and parameters)

demoDepthPro - Run https://github.com/apple/ml-depth-pro A quick, sharp monocular metric depth model.

demoSAM2 - Run https://github.com/facebookresearch/sam2 Segment Anything Model 2

demoVGGT - Run https://vgg-t.github.io/ Visual Geometry Grounded Transformer

Troubleshooting

Path errors

Method 'confirm' is not defined for class 'MPyReq' or is removed from MATLAB's search path.
Error in MPyReq.require (line 268)
tf = MPyReq.confirm(options.InstallConfirmationText);
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The above error occurs when MPyReq.m is not on MATLAB path. Ensure to add the folder containing MPyReq.m to the matlab path using the addpath(folderWithMPyReq) function.

Python Errors or Package Conflicts

MPyReq does not resolve package conflicts. If you tried to install Package A first which used x.xx version of an upstream package U, and then tried to add Package B which used y.yy version of U in the same pyenv session - you will get odd Python errors due to conflicts in required version of Package U. Best strategy is to only work with one 'project' at a time - as shown in the examples. And use terminate(pyenv) between switching projects. MPyReq automatcially does this only when the required Python version changes.

If you have a workflow needing to combine two models which have conflicting requirements, you will have to terminate(pyenv) between calls to these models. For best performance (and when possible), you should run all data through model 1 first, serialize the results into disk, and then run model 2 on the saved data.

win64

MPyReq is expected to work on win64. However, installing CUDA enabled PyTorch has not been tested. MPyReq uses uv as the install engine, so uv environment variables are honored. You can experiment with setting this environment variable before invoking any installs to guide uv to download from the pytorch index

setenv("UV_EXTRA_INDEX_URL","https://download.pytorch.org/whl/cu126")