Python API

Install

Add MedMLX to a Python 3.13 project with uv:

uv add "medmlx[all,mcp]"

For a smaller install, replace all with segment, generate or vision. Import it as medmlx.

Run a model

import json
from pathlib import Path
import medmlx

arguments = json.loads(Path("arguments.json").read_text())
result = medmlx.run("mlx-segment-ct", arguments=arguments, root="/path/to/work")

arguments is a dictionary of the model's arguments, and describe_model lists the ones it accepts. run runs the model in a separate process and waits for it to finish. If you interrupt it, that process stops. Relative paths are read from the root folder.

Functions

• medmlx.run(model_id, *, arguments, root=None)

  Runs a model and waits for it to finish. If you interrupt it, the model stops.

• medmlx.describe_model(model_id)

  Shows the arguments a model takes and how to use them.

• medmlx.model_readiness(model_ids=None, *, arguments=None, root=None)

  Checks that models can run on this Mac. With arguments, it also checks their names and that the input paths exist.

• medmlx.list_models(task=None, family=None)

  Lists the installed models, and any installed model that failed to load.

• medmlx.list_packages()

  Lists the model families, which runtimes are installed and the models each one provides.

• medmlx.list_checkpoints(model_id=None)

  Lists where model checkpoints come from. Downloads nothing.

• medmlx.runtime_info()

  Reports this Mac’s platform and what MLX sees, including whether Metal is available.

• medmlx.setup_model(model_id, *, progress=None, refresh=False)

  Downloads one model’s weights ahead of time.

• medmlx.setup_all(*, progress=None, refresh=False)

  Downloads weights for every installed model. One failure doesn’t stop the rest.

• medmlx.setup_plan(model_id)

  Shows what would download for one model, without downloading it.

• medmlx.list_setup_plans()

  Shows what would download for every installed model.

Weights

Weights download the first time a model runs. To download them ahead of time, call setup_model(model_id) or setup_all(), which work like medmlx setup. setup_plan(model_id) and list_setup_plans() show what would download without downloading it.