Get started with MLX-Reason-CT

Generate a report or ask a question about a chest or abdomen CT. The commands run locally, and this page never reads your scan.

Install

Requires macOS 14.0 or later on Apple Silicon, Python 3.13 and uv. Create an environment and install the MLX-Reason-CT runtime.
Install
```
uv venv --python 3.13
source .venv/bin/activate
uv pip install "mlx-reason-ct>=0.3.6"
```
Download the weights

The pinned revision is 17.4 GB. A run peaks at 22.7 GB of MLX memory, in addition to what preprocessing, macOS and other apps use.
Download
```
mlx-reason-ct download \
  --repo MedMLX/MLX-Reason-CT \
  --revision 5e5b5202fd04ac9f63ede203ebc9327aa676ae94 \
  --model-dir models
```
Prepare the CT

Use one 3D CT volume in NIfTI format (.nii or .nii.gz) with Hounsfield unit values and valid spatial geometry.

Use one NIfTI scan at a time. DICOM files, 2D images and video are not supported.
Crop whole-body scans to the chest or abdomen before running. Automatic cropping can select the wrong region, especially when the arms are raised.
Generate a report

Run this in the directory that holds the CT and the model directory, with the environment active. Relative paths resolve there.
Report
```
mlx-reason-ct report --input='ct.nii.gz' --model-dir='models' --output-dir='outputs'
```
For an abdomen CT add --anatomy-region=abdomen. To ask a question instead of getting a structured report, add --prompt='your question'. Add --enable-thinking to save the reasoning to model_response.json.

Each run writes report.txt, model_response.json and run.json. The package page covers the Python API and other options.