CaImAn: a Python toolbox for calcium imaging analysis

From raw movie to deconvolved neuronal sources

CaImAn is a Python toolbox for large scale calcium imaging analysis, and the repository description names the pipeline stages: movie handling, motion correction, source extraction, spike deconvolution and result visualization. The README expands on that, listing fast and scalable algorithms for motion correction, source extraction, spike deconvolution and registering neurons across multiple sessions.

The audience is a neuroscience lab rather than a generic data science team. It suits both two-photon and one-photon fluorescence microscopy data, and it can run in offline and online modes, which matters when you want to process a recording while it is being acquired rather than after the fact. The documented home for the documentation is caiman.readthedocs.io, and the project is hosted by the Flatiron Institute.

What you get is not a library of small functions but a working pipeline with a method behind it. The reference implementations are named in the demo notebook table: CNMF for two-photon or low-noise one-photon data, CNMFE for one-photon data, and Volpy for voltage data, each tied to a paper. That framing matters, because these are algorithms with parameters that behave differently on different scanners, and the notebooks exist to expose those parameters rather than hide them.

Route A: a conda environment, then caimanmanager install

The README offers two installation routes and is clear about which one to take. Route A is the easiest, install the miniforge distribution of Anaconda and use it to install the rest from prebuilt packages, and the documentation says most users should take this path. The miniforge distribution of conda is preferred because it requires fewer steps and is likely to encounter fewer issues, and if you use another conda distribution you will probably need to add -c conda-forge to the commands you use.

Step one is done in your anaconda prompt, starting in the base environment:

    mamba create -n caiman caiman # build a caiman environment
    conda activate caiman  # activate the environment

Step two creates a working directory called caiman_data holding the code samples and related data, and is run from the same environment:

    caimanmanager install

Step three moves into that directory and starts Jupyter:

    cd <your home>/caiman_data/
    jupyter lab

From there you open demos/notebooks/ and click demo_pipeline.ipynb. The README recommends starting with that CNMF notebook because it contains more explanation and details than the others, and it covers concepts used without explanation elsewhere.

One note for Windows users appears early: they will temporarily need to use an alternative install path.

Route B for Windows needs Visual Studio 2019 and pip install .

Route B is the alternative: have a working compiler, create a Python virtualenv, get the sources and use pip to populate the environment and build Caiman. The README is blunt that this route is not as tested and is not presently documented, and notes that although it is a standard pip based install it will invoke your C++ compiler to build some components.

There is a separate Windows variant, because the general route needs adjustments there. You need Visual Studio 2019 or possibly a later version with the C++ compiler and command line utilities, then clone the repository onto the Windows system and enter the checkout directory. The environment is created mostly empty:

    mamba create -n caiman python=3.11 pip vs2019_win-64
    conda activate caiman

And Caiman itself is installed with pip:

    pip install .

The README calls this step the most fragile part of the install route, and it fails if the compiler is not correctly installed. There is a detail that catches people: after a successful build you are told to leave the source directory, because later steps will not function correctly when run from the source or checkout directory.

Route B also expects you to set environment variables before using Caiman, with a Linux and macOS example and a Windows example in the conda feedstock recipe, either recorded as a note or added to your dotfiles.

The dependency list tells you what the pipeline really uses

The pyproject file names the project caiman and describes it as a library and software for ROI detection and deconvolution of calcium imaging datasets, with a long author list from the Flatiron Institute. The runtime dependencies are where the real picture of the tool appears, and they include av, moviepy and pims for movie handling, h5py and zarr for data storage, opencv-python, scikit-image and scikit-learn for the image processing, torch, torchvision and keras for the component that needs them, pynwb for the neurodata format, and holoviews with bokeh and panel for visualisation. pyside6 sits alongside those, which is a desktop UI dependency in an analysis toolbox.

The first part of that list is:

dependencies = [
  "av",
  "bokeh >= 3.1.1",
  "coverage",
  "cython",
  "h5py >= 3.4.0",
  "holoviews >= 1.16.2",
  "ipykernel",
  "ipython",
  "ipyparallel",
  "ipywidgets",
  "keras",
  "matplotlib",
  "moviepy",
  "mypy",
  "numpy",

The optional extra group is smaller and optional, covering jupyter, jupyter_bokeh, pyqtgraph and tk. The build system itself requires cython, numpy, setuptools and wheel, and the setup.py file shows why a compiler is needed, since it cythonises the sources and builds extension modules. That is the technical reason Route A exists: prebuilt conda packages save you from compiling the package on your own machine.

Notebooks are the interface, and the anchor notebook matters

CaImAn ships demo notebooks for each main feature, from motion correction to online CNMF, and the README tells you how to work through them. Start with the CNMF notebook demo_pipeline.ipynb, which contains more explanation and details than the other notebooks, then the CNMFE notebook demo_pipeline_cnmfE.ipynb, which is also more detailed. Once you have worked through those anchor notebooks, the advice is to pick the demo notebook closest to your own use case and adapt it.

The mapping between use case, notebook and method is given in a table. CNMF for two-photon or low-noise one-photon data goes with demo_pipeline.ipynb and the 2016 Pnevmatikakis paper. CNMFE for one-photon data goes with demo_pipeline_cnmfE.ipynb and the 2018 Zhou paper. Volpy for voltage data goes with demo_pipeline_voltage_imaging.ipynb and the Cai paper.

Two points follow from this structure. The notebooks are the documentation, and the method selection is a real decision: one-photon data is noisier, which is why a separate variant exists for it, and voltage imaging is a different signal that gets its own pipeline. Adopting CaImAn means picking a notebook and tuning its parameters for your scanner, not importing a function.

Upgrading: minor releases are meant to be painless, major ones are not

The upgrading section is unusually specific, and it is worth reading before you pin a version. If you upgrade Caiman you should not generally need to clear out and recreate your caiman_data directory between minor releases, for example from 1.2.3 to 1.2.4, because the project tries to avoid API changes that would break demos between those releases. You will, however, miss out on improvements to the notebooks, and it is normal for people to change notebooks themselves without renaming them.

If you want the latest changes, the documented route is to remove or rename your caiman_data directory, create a new one with caimanmanager install, and then move your data and modified notebooks back in, which means you may still lose notebook improvements that were made upstream.

Across a major version, for example from 1.0.15 to 1.1.0, APIs are more likely to have changed and more substantial changes may be needed to integrate with the new version, though the process is the same. The release history shows why that matters: v1.13.0 on 2025-12-05, v1.13.1 on 2026-01-30 and v1.13.2 on 2026-07-28, so minor bumps arrive with real notebook changes inside them even though the API is meant to hold.

A GPL project with a container recipe and heavy CI

The licence file at the root is LICENSE.txt and the project is under GPL-2.0. That is the single most consequential fact for anyone outside academia, because GPL obligations attach to distributing derived software, and a toolbox whose dependencies include a C++ extension and a large model directory is not trivial to keep at arm's length if you intend to ship it inside a product.

The engineering side shows a project with real infrastructure. There is a Dockerfile that starts from continuumio/anaconda3, installs gcc, g++ and libgl1, creates a conda environment with caiman from conda-forge and then runs caimanmanager install inside it, which is a container route for teams that do not want to manage conda on the host. Continuous integration is split across a Jenkinsfile, a .travis.yml and a GitHub workflows directory, and there is a test directory, a test_demos.sh script that exercises the demo notebooks, a mypy.ini, a pylintrc and a pylint-all.sh, plus a .style.yapf and a .yapfignore for formatting. The repository also keeps a CHANGELOG.txt, a CONTRIBUTING.md, an ISSUE_TEMPLATE.md, a VERSION file, environment.yml and environment-minimal.yml for the environment definitions, and directories for demos, docs, model and example movies.

The last push was on 2026-10-12, so development is current, and the docs build is configured through .readthedocs.yaml with the documentation published at caiman.readthedocs.io.

Editorial conclusion

Adopt CaImAn when you analyse calcium or voltage imaging data and want motion correction, source extraction and deconvolution in one pipeline with notebooks that document the parameters, and when the GPL-2.0 licence is compatible with your work. Do not adopt it if you need a supported source build without a conda environment, because the README states the pip route is not as tested and is not presently documented, or if your product is closed source and cannot carry GPL obligations. Verify first that the caiman environment resolves on your platform, since Windows users are told they will temporarily need an alternative install path, and that the demo_pipeline notebook runs end to end on a small sample before you point the pipeline at a real recording.

Frequently asked questions

Official sources

1. flatironinstitute/CaImAn on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases