Nilearn: scikit-learn style fMRI analysis with masks, atlases and surface support

The gap Nilearn fills between NIfTI files and scikit-learn estimators

A functional MRI run is a four-dimensional array: three spatial axes plus time. A scikit-learn estimator expects a two-dimensional matrix of samples by features. The work between those two shapes is masking, resampling, detrending, and often some form of dimension reduction, and it has to be repeated consistently across subjects. Nilearn targets that gap. The README states the library provides statistical and machine-learning tools for analyses of brain volumes and surfaces, and that it supports general linear model based analysis while using scikit-learn for multivariate statistics. The intended user is a researcher or engineer who already writes Python and wants decoding, predictive modeling, classification, or connectivity analysis without hand-rolling the image handling. It is not a replacement for a full preprocessing pipeline, and the README does not claim to be one.

Maskers, atlases and estimators: the actual data flow

The central abstraction is the masker. You give it an image or a set of images and a mask, and it extracts the voxel or region time series into a two-dimensional array. From there the data is ordinary NumPy, which means any scikit-learn estimator, pipeline, or cross-validation splitter can be applied. Atlases are the second half of that idea: instead of voxelwise features you can extract one time series per region of interest, which shrinks the feature count and makes connectivity matrices tractable. The README names brain-connectivity, decoding, MVPA and fMRI among the repository topics, and describes applications such as predictive modeling, classification, decoding, and connectivity analysis. Surface support is stated in the README's first line, which says Nilearn enables analyses of brain volumes and surfaces, so the same style of workflow is meant to extend to mesh data rather than being volume-only. The GLM side sits alongside the multivariate side, which matters because a decoding result is usually more convincing when a univariate GLM contrast points the same way.

Installing Nilearn and the optional plotting extras

The README recommends a virtual environment, either venv or conda, before installing. With venv the commands are python3 -m venv /<path_to_new_env> followed by source /<path_to_new_env>/bin/activate, with Windows users changing the second line to \<path_to_new_env>\Scripts\activate.bat. With conda the README gives conda create -n nilearn python=3.11 and conda activate nilearn. The install itself is python -m pip install nilearn, and upgrading is python -m pip install --upgrade nilearn. Plotting dependencies are separate: matplotlib and plotly are described as optional, installed with python -m pip install 'nilearn[plotting]' or python -m pip install 'nilearn[plotting, plotly]'. The README states that matplotlib >= 3.8.0 is required if you use plotting functionality or run the examples, and that using the plotly engine in supported plotting functions requires both plotly and kaleido. Verification is a single import: import nilearn, with no error meaning the install worked. The required dependency list lives in pyproject.toml rather than in the README, so that file is where you check version pins before pinning your own environment.

Where the pre-1.0 version number and dependency surface bite

The releases listed run 0.14.0rc0, then 0.14.0, then 0.14.1, so the project is still on a zero-major version. That is a signal about API stability, not about quality: a minor bump can carry renames or deprecations that break notebook code written against the previous minor. If you maintain a shared analysis repository across a lab, that is a real cost, and pinning nilearn in your requirements file is the practical response. The second constraint is the dependency surface. Plotting pulls matplotlib, and the plotly engine pulls plotly plus kaleido on top. Tests need pytest >= 6.0.0 and pytest-cov according to the README. None of these are unusual for scientific Python, but they mean a minimal container image will grow once you touch the visualization functions. The README does not document memory limits or out-of-core handling for large 4D datasets, so if your images are large, that is something to measure in your own environment rather than assume.

A concrete case where Nilearn is the wrong tool

If your question is a standard group-level activation analysis with a design matrix, motion regressors, and cluster-level correction, and your team already runs FSL FEAT or SPM, adding Nilearn does not simplify that path. Nilearn's GLM support exists, but the library's distinguishing contribution is the bridge to scikit-learn style multivariate analysis. Choosing it for a pipeline that a mature, GUI-driven package already covers end to end means you take on Python API churn in exchange for flexibility you are not using. The same applies if you need a frozen interface for a clinical or regulated product: a zero-major library with releases at 0.14.1 is not the place to build that. A third case is a team with no Python at all. The install instructions assume a Python environment and pip; there is no non-Python entry point described in the README.

How this differs from FSL, SPM and plain scikit-learn

FSL and SPM are complete neuroimaging suites: they ship preprocessing, registration, GLM fitting and visualization behind their own command-line or GUI interfaces, and their Python bindings expose those tools rather than reimplementing them in Python. Nilearn takes the opposite approach. It is a Python library first, and the README frames it as leveraging scikit-learn for multivariate statistics. That difference shows up in what you can compose: with Nilearn you can drop a masker's output into a scikit-learn Pipeline, swap in a different estimator, or run cross-validated decoding with the same tools you would use on tabular data. Plain scikit-learn, obviously, has no concept of a NIfTI header, an affine transform, or a brain mask, which is exactly the layer Nilearn supplies. The trade-off is that Nilearn does not try to be a preprocessing suite, so registration and distortion correction still come from elsewhere in your stack.

Maintenance, licence and what to verify before you commit

The licence is BSD-3-Clause, a permissive licence that generally allows use in closed products provided the copyright notice and disclaimer are retained. That is a statement about the licence text, not legal advice; if you are embedding Nilearn in a commercial product, have your own counsel read the BSD-3-Clause terms. On maintenance, the repository is not archived, the default branch is main, and the most recent push recorded is 2026-09-09, with 0.14.1 released on 2026-09-04. Those dates indicate an active release cadence, and the README points to a contribution guide, a Discord, a Mastodon account, a Bluesky account, and weekly drop-in hours every Wednesday from 4pm to 5pm UTC on Jitsi Meet, which the README says are attended by at least one core developer. The upgrade cost is the usual one for a zero-major scientific library: read the release notes for each minor version you cross, and pin the version in your environment file. The README does not state a support window or an LTS policy, so plan upgrades as a recurring task rather than a one-time install.

Editorial conclusion

Adopt Nilearn if you already work in Python and need to turn NIfTI volumes or surface meshes into arrays that scikit-learn estimators can consume, without writing your own resampling and masking code. Do not adopt it if you need a stable, frozen API for a product, or if your analysis is a standard group-level GLM that a tool like FSL or SPM already covers with a tested pipeline. Before committing, check the pyproject.toml dependency list against your environment, and confirm the 0.14.1 release notes for any deprecations that touch the functions you plan to call.

Official sources

1. License: BSD-3-Clause
2. nilearn/nilearn on GitHub
3. Project website
4. README
5. Releases