Installation

This guide explains how to install MuscleMap and its dependencies for automated muscle segmentation and quantification from MRI and CT scans.

Dependencies

  • Python: 3.9.23
  • Operating system: Linux, macOS, or Windows

The MuscleMap Toolbox works on CPU and GPU, but performance is substantially faster with GPU acceleration.

1. Install Anaconda

We recommend installing Miniconda or Anaconda through the following links:

2. Create and activate a conda environment 

conda create --name MuscleMap python=3.9.23
conda activate MuscleMap

3. Download the MuscleMap repository

Option A — Using Git 

git clone https://github.com/MuscleMap/MuscleMap.git
cd MuscleMap

Option B — Download ZIP

  1. Open https://github.com/MuscleMap/MuscleMap
  2. Click the green <> Code ▼ button
  3. Click Download ZIP
  4. Unzip the archive
  5. Navigate to the extracted folder:
cd MuscleMap

4. Install MuscleMap in editable mode 

pip install -e .

This installs all required packages and registers the command-line tools:

  • mm_segment
  • mm_extract_metrics
  • mm_register_to_template
  • mm_gui
Note
Installing MuscleMap includes a default CPU-only installation of PyTorch. If you want to use a GPU for faster inference, please proceed to Step 5.

5. (Optional) Install PyTorch with GPU support

If you plan to run MuscleMap on CPU only, you may skip this step.

To use a GPU, you need one of the following:

  • NVIDIA GPU with a compatible CUDA runtime
  • AMD GPU with ROCm support

Step 5.1 — Check if CUDA is already available

Open a Python console:

import torch
print("Is CUDA available?:", torch.cuda.is_available())
  • True → CUDA is available and ready
  • False → continue with the steps below

Step 5.2 — Check your system GPU runtime

In a terminal, run:

NVIDIA (CUDA):

nvidia-smi

AMD (ROCm):

rocm-smi

This tells you which CUDA or ROCm version your system supports.

Step 5.3 — Install a compatible PyTorch version

Install PyTorch matching your system configuration.

We recommend using pip and following the official PyTorch instructions.

Find the Pytorch installation here

Example (CUDA, adjust version as needed):

pip install torch==2.4.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
Note
Make sure the CUDA version of PyTorch matches the CUDA runtime reported by nvidia-smi. Also, we recommend to install Pytorch using the wheel.

6. Verify the installation

Run:

mm_segment --help
mm_extract_metrics --help
mm_register_to_template --help
mm_gui --help

If these commands print a help message instead of an error, the installation was successful. If you still find problems with installation, please open a GitHub issue with an example.