MedMLX

Model setup for applications

Install the setup extra to use medmlx setup MODEL --progress. It reuses explicitly supplied model directories, the MedMLX asset cache, or the Hub cache, then downloads missing native files and retains publisher notices. It returns the runner arguments for the application to remember. Downloads can be resumed by running setup again; --plan only describes the operation.

medmlx.list_setup_plans(), setup_plan(model_id), and setup_model(model_id, existing_paths=..., progress=...) expose the same actions to Python clients. The default asset cache search is ~/.cache/medmlx (override with MEDMLX_ASSET_CACHE); downloads use the normal Hugging Face cache. Setup supports published VISTA3D CT, Reason-CT, FleXray flagship, and named BraTS bundles, plus the radiomics runtime. Other checkpoints require their provider's setup. Runtime installation uses this release's family pins. Frozen applications must already bundle the runtime; setup can still download their model files. An already installed runtime is detected by package metadata and is not checked against the family pin or imported by that check. Setup checks required files and available provider admission contracts. Model execution retains responsibility for tensor compatibility and input validation.

One Python API, command line and MCP server for native medical imaging on Apple Silicon. Run TotalSegmentator, nnU-Net, MedSAM2, SynthSeg and more through their independent MLX runtimes.

Models · Docs · Website

Apple Silicon · Metal · Python 3.13 · uv

Install

Install all model families with MCP and model setup support:

uv venv --python 3.13
source .venv/bin/activate
uv pip install "medmlx[all,mcp,setup]"
medmlx models

Choose segment, generate or vision instead of all for a smaller install. The segment extra includes SAM3 image/video support; generate includes NV-Reason-CT and the weight-free FDG PET adapter. Model weights have their own download and access requirements. Provisional medgemma and lingshu adapters use an explicitly selected separate MedVLM environment; real-checkpoint inference through these bridges is unqualified. The MedVLM runtime is not bundled because its MLX and Transformers requirements conflict with the unified environment. See the bridge setup and limits and dependency compatibility notes.

Run a model

medmlx describe totalsegmentator
medmlx readiness totalsegmentator --arguments arguments.json --root /path/to/work
medmlx checkpoints --model-id nnunet
medmlx run totalsegmentator --arguments arguments.json --root /path/to/work

describe includes the provider's full instructions and argument descriptions, including documented units and ranges. Descriptions reproduce provider documentation; they do not establish validated constraints or numerical qualification. Relative paths resolve against --root. Readiness preserves ready as a boolean for imports/provider checks and Metal; runtime_ready makes that same limited meaning explicit. Neither validates run inputs or weights. The separate run_ready is false for a known blocker and null while input/checkpoint contents remain unverified; this check never returns run_ready=true. Passing arguments checks names, required arguments and local input/weight path existence, without running inference or creating outputs.

checkpoints lists five source references, including catalog-only liver and AutoPET entries for the general nnU-Net provider. It neither stages assets nor qualifies a checkpoint. The same action is available as list_checkpoints in Python and MCP.

import json
from pathlib import Path
import medmlx

arguments = json.loads(Path("arguments.json").read_text())
result = medmlx.run("totalsegmentator", arguments=arguments, root="/path/to/work")

For an MCP client, use medmlx serve --root /path/to/work as its stdio command. Jobs belong to that server session; disconnecting cancels workers and their child processes. Client registration and persistent filesystem access are configured by that client, not changed by this package. Some providers fetch default assets when paths are omitted; supply explicit local checkpoints for offline execution. See the MCP guide for client setup, tools, and a complete job workflow. For checkpoint conversion and development, see conversion and core.

License

Apache-2.0. See third-party notices. Runtimes and model weights retain their own terms.

For research and education. Outputs require human review.