Nilearn: statistical and machine-learning analysis of brain volumes and surfaces in Python

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

A brain image is a four-dimensional array with a spatial affine attached. Scikit-learn expects a two-dimensional matrix of samples and features. Nilearn exists to bridge that mismatch, and the README states the intent plainly: it "enables approachable and versatile analyses of brain volumes and surfaces" and "leverages the scikit-learn Python toolbox for multivariate statistics." The audience is researchers and engineers who can already load a NIfTI file with nibabel but do not want to hand-roll masking, resampling and cross-validation for every study. The repository topics confirm the scope: fmri, decoding, mvpa, brain-connectivity, machine-learning. If your work stops at reading headers and converting formats, you do not need this library. If it continues into "does this contrast survive a second-level model" or "can a classifier tell conditions apart," that is the layer Nilearn occupies.

How Nilearn turns images into estimators: masking, GLM and connectivity

The mechanism is a pipeline of objects rather than a monolithic command. A masker defines which voxels matter: it takes a 4D image series and extracts the time series inside a mask, producing a samples-by-features array. That array is what the rest of the library consumes. For first-level analysis, the GLM objects fit a design matrix against the extracted signal and produce contrast maps. For second-level analysis, contrast images from several subjects become inputs to a group model, which is why the related searches include "nilearn second level model" as a distinct query. For connectivity, the same masked time series feed correlation or covariance estimators, and Nilearn inherits scikit-learn's fit and transform conventions so that a decoder is a classifier wrapped around masked data. The examples directory mirrors this structure directly: 04_glm_first_level, 05_glm_second_level, 03_connectivity, 02_decoding. That layout is the clearest statement of the intended data flow.

Installing Nilearn and running a first masked analysis

The README recommends a virtual environment before anything else, managed either with the standard library venv or with conda. Creating and activating one with venv looks like this, and on Windows the activation line changes to the Scripts\activate.bat path the README gives.

python3 -m venv /<path_to_new_env>
source /<path_to_new_env>/bin/activate

With conda the README gives a Python 3.11 environment instead:

conda create -n nilearn python=3.11
conda activate nilearn

Once the environment is active, install the package. The base install pulls the required dependencies listed in pyproject.toml; the plotting extra adds matplotlib, which the README says is also needed to run the examples.

python -m pip install nilearn
python -m pip install 'nilearn[plotting]'

The README's own check is a single import. If no error is raised, the installation is correct.

import nilearn

For a first real use, the repository's examples directory is the intended path rather than a single documented entry command. The numbered folders 00_tutorials, 01_plotting, 02_decoding, 03_connectivity, 04_glm_first_level, 05_glm_second_level, 06_manipulating_images and 07_advanced each hold runnable scripts, and the README points to them as the place where plotting functionality and the wider workflow are exercised.

Where Nilearn stops: preprocessing, surfaces and the plotting extras

Nilearn is not a preprocessing suite. The README describes statistical and machine-learning tools, GLM-based analysis and scikit-learn-backed multivariate statistics. It does not claim motion correction, slice-timing correction or distortion unwarping, and nothing in the repository layout suggests those steps live here. If your data has not been preprocessed, you are looking at the wrong layer of the stack. A second boundary is plotting. The README states that matplotlib >= 3.8.0 is required for plotting functionality and for running the examples, and that some plotting functions support both matplotlib and plotly as engines, with plotly requiring both plotly and kaleido. Those are optional extras, not defaults, and the pyproject.toml pins them in a separate dependency group (min_plotting) alongside kaleido==1.1.0, matplotlib==3.8.0 and plotly==6.1.1. Install the base package and then wonder why a figure fails, and the answer is usually a missing extra rather than a bug.

Nilearn compared with nibabel and SPM

The most common comparison is with nibabel, and the split is clean. Nibabel reads and writes neuroimaging file formats and exposes the array plus affine. Nilearn builds on top of that layer to provide statistical and machine-learning tools. Choosing between them is not a real choice: if you need multivariate statistics, nibabel alone leaves you writing the masker and the cross-validation loop yourself. The comparison with SPM is different in kind. SPM is a MATLAB environment with its own preprocessing and statistics workflow; Nilearn is a Python library that plugs into scikit-learn, so its estimators compose with pipelines, grid search and metrics from that ecosystem. The trade-off is that Nilearn gives you components and expects you to assemble them, while SPM gives you a guided workflow. Nipype sits elsewhere again, as a workflow engine for orchestrating tools including SPM and FSL; Nilearn is a library you call, not an engine that schedules heterogeneous packages.

Maintenance, releases and what the BSD-3-Clause licence means here

The repository is not archived, and the last push was on 2026-09-09, which is recent enough that the project is being worked on. Releases are frequent: 0.14.1 on 2026-09-04, 0.14.0 on 2026-07-02, and a release candidate 0.14.0rc0 on 2026-04-16. That cadence matters for upgrade cost, because the pyproject.toml pins a minimum dependency set (joblib, nibabel, numpy, pandas, requests, scikit-learn, scipy, jinja2) and the comment in that file notes that scikit-learn 1.7.0 has a bug affecting _repr_html_, which is why the pin excludes it. A dependency floor that tracks scikit-learn releases means an environment upgrade can be blocked by a single package. The licence is BSD-3-Clause, a permissive licence that generally allows reuse and redistribution with attribution and without a copyleft obligation on your own code; that is a description of the licence identifier, not legal advice, and anyone embedding Nilearn in a product should read the LICENSE file and their own counsel's guidance. The README points to a contribution guide for development setup, and the project runs weekly drop-in hours every Wednesday from 4pm to 5pm UTC on Jitsi Meet, which is an unusual and concrete support channel for a scientific library.

What to check before you build a pipeline on Nilearn

Start with the examples directory rather than the README, because the README is an install and community document and the examples are where the statistical intent is visible. The numbered folders (00_tutorials through 07_advanced) tell you what the maintainers consider the canonical path through the library. Second, confirm your input format is one nibabel reads, since Nilearn's maskers operate on images already in memory. Third, decide early whether you need plotting, and install the extras at environment creation time rather than after the first failed figure. Finally, note the AGENTS.md and CLAUDE.md files at the repository root: their presence indicates the project has written guidance for automated contributors, which is worth reading if you plan to submit changes rather than only consume the library.

Editorial conclusion

Adopt Nilearn if your analysis lives in Python, your images are already in a format nibabel reads, and you want GLM, decoding or connectivity results that behave like scikit-learn estimators. Do not adopt it if your lab's pipeline is built around SPM or FSL batch scripts and nobody wants to maintain Python packaging; Nilearn does not replace those tools' preprocessing stacks. Before committing, verify that the plotting extras you need (matplotlib, plotly plus kaleido) install cleanly in your environment, and read the examples directory matching your modality, since the README alone does not document the statistical assumptions behind each estimator.

Frequently asked questions

Official sources

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