Skip to content

Building a MATLAB Gear

MATLAB is widely used in the scientific community, and many Flywheel users want to package MATLAB code as a gear. The supported approach is to compile your MATLAB code with the MATLAB Compiler and run it inside a gear using the MATLAB Compiler Runtime (MCR), which MathWorks distributes free of charge.

Reference example: matlab-mcr-example

Flywheel maintains a working example gear that you can fork or copy as the starting point for your own MATLAB gear:

matlab-mcr-example

The example is intentionally minimal — it appends a configurable line to an input text file — so the value is in the wiring, not the algorithm. Replace the MATLAB and Python pieces with your own code while keeping the overall layout.

The repository's README.md is the authoritative build-and-deploy reference. This page is a high-level overview of the approach so you can decide whether it fits your use case before diving into the example.

How the example is structured

The gear bundles three pieces inside a single Docker image:

  1. A Python skeleton that handles gear I/O, reads the gear configuration through fw_gear.GearContext, and is the process the Flywheel engine invokes.
  2. A compiled MATLAB binary produced from your MATLAB sources with mcc. The Python skeleton calls this binary as a subprocess.
  3. The MATLAB Compiler Runtime (MCR), installed into the image from MathWorks' official silent installer on top of the mathworks/matlab-runtime-deps base image.

Python and MATLAB communicate through a small JSON file that the parser writes into the gear's work/ folder. The compiled MATLAB binary reads that file to discover input paths, the work and output directories, and any user-supplied parameters.

The example follows the conventional work/ → output/ discipline: intermediate files stay under work/ (which the runtime wipes between runs), and only deliverables are moved to output/.

Things to know before you start

  • Compile on Linux. MATLAB binaries cannot be cross-compiled. You need a Linux host with MATLAB installed and a valid Compiler license to produce the standalone binary that ships inside the gear.
  • MATLAB and MCR versions must match exactly. The MATLAB release used to compile the binary must equal the MCR release installed in the image. The example pins both to R2025b; to target a different release, update the MCR_RELEASE and MCR_UPDATE build args in the Dockerfile, recompile your MATLAB code against that release, and update the release-tagged paths in the Dockerfile and manifest.json environment block (LD_LIBRARY_PATH, XAPPLRESDIR).
  • No GUI interactions. Gears run headless, so any MATLAB code that requires a GUI or mid-stream user input is not supported.
  • MCR base images come from MathWorks. Flywheel no longer publishes pre-built MCR images. The example installs MCR directly from MathWorks' official distribution, which is the recommended pattern for new gears.

Calling the Flywheel SDK from MATLAB

If your MATLAB algorithm needs to read or write Flywheel metadata, fetch additional files, or write analysis outputs back to a project, you can call the Flywheel Python SDK directly from MATLAB. See Call flywheel-sdk from MATLAB.