MambaIRv2 gives a state space model a way to look at the whole image

Two papers share one repository, and the old one stays on a branch

The repository holds both generations of the work. MambaIR, a simple baseline for image restoration with a state space model, was accepted at ECCV 2024, and MambaIRv2, attentive state space restoration, was accepted at CVPR 2025, with the paper on arXiv as 2411.15269. The project explains the arrangement plainly: the updated MambaIRv2 is totally compatible with the previous MambaIR, and the code of the first version is kept in a separate branch, mambair, in case you want to revisit it. The audience is image restoration researchers and the engineers who build on top of published backbones. The scope is worth stating too, because the repository is not a general super-resolution toolkit. It is the code for a model, with the configs to train and test it, the weights for the released models, and the analysis scripts used to produce the complexity numbers in the paper. The related collection of Awesome Mamba in Low-Level Vision is linked from the README as the wider survey.

The causal limitation that MambaIRv2 is built to remove

The argument goes like this. Mamba based image restoration backbones have shown the potential to balance global reception with computational efficiency, but Mamba has an inherent causal modeling limitation, where each token depends solely on its predecessors in the scanned sequence. For an image, that restricts how much of the picture a pixel can use, and it is a poor fit for restoration, which needs to reason about the whole degraded region. MambaIRv2's answer is to give Mamba a non-causal modeling ability similar to ViTs, which the authors call attentive state space restoration. The mechanism is an attentive state space equation that allows the model to attend beyond the scanned sequence, and it has a practical consequence: image unfolding can be done with a single scan rather than repeatedly. The abstract reports that this outperforms SRFormer by 0.35 dB PSNR for lightweight super-resolution even with 9.3 percent fewer parameters, and suppresses HAT on classic super-resolution by up to 0.29 dB. Those are the authors' own numbers from the abstract, and the repository also carries a pipeline diagram for the model.

A second mechanism for interaction between distant similar pixels

Beyond the attentive state space equation, the second contribution is a semantic-guided neighboring mechanism, whose stated purpose is to encourage interaction between distant but similar pixels. Read together, the two mechanisms address different failure modes. The attentive equation removes the sequential restriction, so a token is no longer limited to what came before it in the scan. The neighboring mechanism then adds a content-driven, long range connection on top, so two pixels that are far apart in the image but semantically alike can still influence each other. The project also maintains a MambaIR-light variant, whose code was updated in March 2024, and the news list records an updated arXiv version in October 2024 in which the results on the light super-resolution tasks were fixed. The paper names behind the work are listed in the README, with equal contribution marked for the first two authors, and the project is presented as an academic release with the weights hosted on Hugging Face under the cguoh account.

The environment is a 2023 conda export with a CUDA extension

There is no pip install to speak of. The repository ships an environment.yaml and a requirements.txt that is a full conda export, linux-64 and Python 3.8, and the header of that file explains how it is meant to be used:

conda create --name <env> --file <this file>

The dependency list fixes the whole stack rather than the interesting parts, so read it as a snapshot. It pins CUDA 11.7 components, cmake 3.28.1, einops, huggingface-hub, imageio, and causal-conv1d at 1.0.0, which is the selective scan convolution that the Mamba family depends on. The build itself compiles a native extension, and setup.py says so in its imports:

from torch.utils.cpp_extension import BuildExtension, CppExtension, CUDAExtension

setup.py also generates a version file from a VERSION file and the current git hash, falling back to the string unknown when the source tree is not a git checkout. The practical warning is that a 2023 environment export with pinned CUDA 11.7 wheels is the kind of dependency set that has to be rebuilt rather than installed on a current machine, and a CUDA extension has to be compiled for your GPU architecture. The team did publish an online jupyter notebook demo for fast inference with the MambaIR model in January 2025, which is the lowest-friction way to see the model work.

The complexity numbers in the first release were wrong, and the fix is in the repo

This is the most useful thing in the README for anyone comparing the model to others, because it is a correction issued by the authors. In August 2024 the project reported that the previous parameter and MACs calculation for the Mamba model using the thop library had a bug, an issue that was also discussed in issue 44. The corrected calculation uses fvcore and additionally registers the parameters that were previously missing, and the new code lives in analysis/flops_param_fvcore.py. The README states the complexity obtained from the new code is larger than the reported one, and promises a new comparable MambaIR-light model. The general shape of the repository follows the same layout, with analysis/ for the complexity and ERF visualisation code, options/ for the training and testing configuration, experiments/ for the experiment scripts, datasets/ and realDenoising/ for the data handling, and a vendored basicsr/ directory that the model builds on. The lesson for a reader is that the parameter counts in the paper, and in many comparison tables built on it, are the buggy ones.

What the release contains, and where it falls short

The repository has one tagged release, v1.0, published on 2024-12-05, and its title names what it carries, the pretrained models and visual results of MambaIRv2. The news list records the rest of the timeline. The repository was released on 2024-02-27, the arXiv paper arrived on 2024-02-23, and pretrained weights for super-resolution and real denoising became available on 2024-03-01, followed in March by the first Mamba based real-world super-resolution model. Configuration files for Gaussian colour image denoising were released on 2024-06-10, and configuration files for JPEG compression artefact reduction on 2024-07-04, with pretrained weights for both following. The licence is Apache 2.0, and the last push was on 2026-06-03. The honest limits are these. It is a research code release, not a maintained library, so there is no API contract, no versioning discipline and no test suite you can rely on. The task coverage is restoration, with super-resolution, real denoising, Gaussian colour denoising and JPEG artefact reduction in the configs, and it does not cover generation or other vision tasks. And the training path assumes a CUDA GPU, so if you need it to run on CPU or on an unsupported accelerator, the repository does not document a route to that.

Editorial conclusion

MambaIRv2 is worth a look for a research team working on image restoration, especially super-resolution and real-world degradation, because the attentive state space equation is a specific answer to a specific weakness of causal scanning and the code, configs and weights are all released. It is not a drop-in library for a production pipeline, since the project is a research release with one tagged version, its own note about previously wrong parameter counts, and a dependency on a CUDA extension build. Before you build on it, read the corrected complexity analysis in analysis/flops_param_fvcore.py rather than the numbers in the paper, confirm the released weights match the task you need, and check whether the fixed, 2023 vintage environment requirements still install on your CUDA version.

Frequently asked questions

Official sources

1. csguoh/MambaIR on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases