# Mamba YOLO: putting a state space model behind a YOLO detector

> Mamba YOLO is a PyTorch implementation of the AAAI 2025 paper of the same name, and its interest is less the numbers in the model zoo than the fact that the selective scan from VMamba is bolted onto an unmodified Ultralytics detection stack, which is what makes it a baseline rather than a framework.

**HZAI-ZJNU/Mamba-YOLO** — the official pytorch implementation of “Mamba-YOLO：SSMs-based for Object Detection”

- Repository: https://github.com/HZAI-ZJNU/Mamba-YOLO
- Stars: 657 · Forks: 67
- Language: Python
- License: AGPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/hzai-zjnu-mamba-yolo

## The model zoo, and what the numbers say

The project is the official PyTorch implementation of the paper Mamba YOLO: A Simple Baseline for Object Detection with State Space Model, published at AAAI 2025 by Zeyu Wang, Chen Li, Huiying Xu, Xinzhong Zhu and Hongbo Li. Three models were pre-trained from scratch and evaluated on the MSCOCO2017 validation set, and the table gives parameters, FLOPs and AP broken down by object size. Mamba YOLO-T is 5.8M parameters and 13.2G FLOPs with 44.5 overall AP. Mamba YOLO-B is 19.1M and 45.4G with 49.1 AP. Mamba YOLO-L is 57.6M and 156.2G with 52.1 AP. The breakdown matters for anyone with a fixed latency budget, because the small and large object AP columns move a lot between models: T gets 24.7 AP on small objects against L's 34.1.

## This is Ultralytics with a different backbone

The acknowledgement section is the most important line for anyone deciding whether to use this. The repository is modified from the open source real-time object detection codebase Ultralytics, and the selective scan comes from VMamba. That inheritance is visible in the layout. The whole ultralytics/ directory is present with the model configurations under ultralytics/cfg/models/mamba-yolo/, and the training entry point is a single script at the root, mbyolo_train.py. The packaging is Ultralytics' own pyproject.toml, naming the project ultralytics, with the AGPL-3.0 licence and the YOLOv8-era description, and the directory tree carries the usual mixture of a research project and a vendored framework. The practical consequence is that anything you know about Ultralytics training, configuration and inference applies here, and that the licensing terms of both upstream projects come with it.

## Getting the environment into a working state

The installation path is spelled out and it is specific about versions. Mamba YOLO is developed based on torch 2.3.0, pytorch-cuda 12.1 and CUDA version 12.6, and the badge line names Python 3.11. You clone the project first.

```bash
git clone https://github.com/HZAI-ZJNU/Mamba-YOLO.git
```

Then you create and activate a conda environment.

```bash
conda create -n mambayolo -y python=3.11
conda activate mambayolo
```

Next comes torch itself, at the pinned version.

```bash
pip3 install torch===2.3.0 torchvision torchaudio
```

And then the dependencies, including the selective scan extension, which is built locally rather than installed from a wheel.

```bash
pip install seaborn thop timm einops
cd selective_scan && pip install . && cd ..
pip install -v -e .
```

That third command is the one to budget time for, because selective_scan is a compiled extension and you are compiling it on the machine you are working on. The final editable install of the project itself is what lets you change the code and rerun without reinstalling.

## Preparing the dataset in the expected layout

The dataset step is a directory structure, and the structure is prescribed rather than discovered. Your dataset should look like this.

```
├── coco
│   ├── annotations
│   │   ├── instances_train2017.json
│   │   └── instances_val2017.json
│   ├── images
│   │   ├── train2017
│   │   └── val2017
│   ├── labels
│   │   ├── train2017
│   │   ├── val2017
```

The labels directory is the part worth noting. A dataset with only images and annotations is not enough here, because the training pipeline expects a labels tree in the YOLO format alongside the COCO annotation json files, with train2017 and val2017 subdirectories under each. If you are coming from a COCO dataset you have not prepared for YOLO training, that conversion is your first piece of work, and it is not something this repository does for you.

## Training the smallest model

Training is one script with a task flag, a data configuration, a model configuration and an output location. The example trains Mamba-YOLO-T on MSCOCO with automatic mixed precision.

```bash
python mbyolo_train.py --task train --data ultralytics/cfg/datasets/coco.yaml \
 --config ultralytics/cfg/models/mamba-yolo/Mamba-YOLO-T.yaml \
--amp  --project ./output_dir/mscoco --name mambayolo_n
```

The flags follow the Ultralytics convention exactly, so --task selects the mode, --data points at a dataset yaml, --config points at the model yaml, and --project and --name decide where the run lands. The --amp flag enables automatic mixed precision. Changing Mamba-YOLO-T to Mamba-YOLO-B or Mamba-YOLO-L is a matter of pointing --config at a different file, and the model zoo links each variant to its own yaml, which is where you would also change the width and depth if you wanted a configuration that is not one of the three published ones. The yolov8n.pt file at the repository root is a pretrained YOLOv8 nano checkpoint, and the tests/ directory holds the test code.

## What the selective scan changes, and what it costs

The project is called a simple baseline, and the framing is deliberate. A state space model is a different family of sequence operator from the convolutional or attention blocks that normally sit in a YOLO backbone, and the paper's claim is that swapping it in gives competitive accuracy with a straightforward recipe rather than a new training regime. The FLOPs column in the model zoo is the number to look at if you care about inference cost, and it moves fast: 13.2G for T, 45.4G for B and 156.2G for L, which is more than a tenfold jump across three model sizes. The vmamba origin of the selective scan also means the code carries assumptions from a vision state space model project, so the selective_scan extension is not a generic utility but a specific piece of compiled code with its own build step, which is why it is installed separately from the rest of the dependencies.

## Where this is the wrong choice

Three things make this a paper implementation rather than a product. The first is version pinning. torch is fixed at 2.3.0 with a specific CUDA build, and there is no indication that newer versions are supported, which means the environment is a known-good combination rather than a current one, and a machine with a newer GPU driver will want the older stack. The second is the licence. AGPL-3.0 applies to the project and to the Ultralytics packaging it carries, and for a company shipping a product built on this, that is a decision to make deliberately rather than to discover later. The third is the absence of releases. The repository publishes no GitHub releases at all, the last push was on 2026-09-10, and the model zoo numbers come from the paper rather than from a tracked release of the code. If you want a detector to run in production, a maintained YOLO implementation with a version history and a maintainer answering issues is a safer bet, and this repository is worth using for the architecture idea and for comparing results rather than as a dependency.

## Conclusion

Mamba YOLO fits a researcher who wants a working selective scan inside a detection model rather than a reading of the paper, since the implementation ships T, B and L configurations with published MSCOCO2017 numbers and training scripts for each, and it fits anyone who wants to compare a state space model backbone against a YOLO baseline on the same codebase. It does not fit a team that wants a supported, current project, because the repository publishes no GitHub releases and the last push was on 2026-09-10, and it does not fit someone who wants a permissive licence, since the project is AGPL-3.0 and the packaging is Ultralytics' own. Before you build on it, read the model zoo table against your hardware budget, since the L configuration costs 156.2G FLOPs against 13.2G for T, and expect to install torch at the pinned 2.3.0 with a CUDA 12.1 build and compile the selective_scan extension yourself.

## FAQ

### What is Mamba YOLO and what does it add to YOLO?

It is the official PyTorch implementation of the AAAI 2025 paper Mamba YOLO: A Simple Baseline for Object Detection with State Space Model. The repository is modified from the Ultralytics real-time object detection codebase, and the selective scan comes from VMamba, so the state space model replaces the usual backbone inside an otherwise standard YOLO stack.

### What accuracy do the Mamba YOLO models reach on MSCOCO2017?

Mamba YOLO-T has 5.8M parameters, 13.2G FLOPs and 44.5 AP, Mamba YOLO-B has 19.1M parameters, 45.4G FLOPs and 49.1 AP, and Mamba YOLO-L has 57.6M parameters, 156.2G FLOPs and 52.1 AP. The models were pre-trained from scratch and evaluated on the MSCOCO2017 validation set.

### How do I install Mamba YOLO?

Clone the repository, create a conda environment with Python 3.11, install torch 2.3.0 with torchvision and torchaudio, then install the dependencies including the locally compiled selective_scan extension, and finally install the project in editable mode with pip install -v -e . The project expects torch 2.3.0, pytorch-cuda 12.1 and CUDA 12.6.

### How do I train Mamba YOLO on MSCOCO?

Prepare the dataset with annotations, images and labels directories for train2017 and val2017, then run python mbyolo_train.py with the --task train flag, a dataset yaml, a model config yaml such as Mamba-YOLO-T.yaml, the --amp flag and an output project directory.

## Sources

- [HZAI-ZJNU/Mamba-YOLO on GitHub](https://github.com/HZAI-ZJNU/Mamba-YOLO)
- [Issues](https://github.com/HZAI-ZJNU/Mamba-YOLO/issues)
- [License: AGPL-3.0](https://github.com/HZAI-ZJNU/Mamba-YOLO/blob/main/LICENSE)
- [README](https://github.com/HZAI-ZJNU/Mamba-YOLO/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hzai-zjnu-mamba-yolo