Nilearn development process

How to help?

  • You are new to python and you don’t know how to do xy

  • If you discovered a bug, but don’t know how to fix it

  • If you discovered a bug and know how to fix it, but don’t know how to get your code onto github (ie, you have some Python experience but have never have used git/github, or have never written tests)

  • You want to contribute code

    • See below

How do we decide what codes goes in?

Scope of the project

Nilearn strives to develop open and powerful statistical analysis of brain volumes (as produced by multiple modalities: MRI, PET, and others). Its focus is to reach end users of the methods (as opposed to methods developers).

Nilearn targets ease of use, but as Python code. In other words, we will not add graphical user interfaces, but we want our code to be as easy to understand as possible, with easy prototyping and debugging, even for beginners in Python.

We are parsimonious in the way we add features to the project, as it puts on weight. Criteria include:

  • It must be in the scope of the project

  • It must correspond to an established practice (typically as used in scientific publications)

  • It must have a concrete use case that can be demo-ed simply with nilearn: an example, on real data, understandable by end-users.

Part of the decision will also be about weighing the benefits (i.e., new features or ease of use for the users) with the cost (i.e., complexity of the code, runtime of the examples).

In practice:

  • The new feature must be demoed in an example in a way that shows its benefit to new users.

  • Because our infrastructure is limited, running all the examples must lead to downloading a limited amount of data (gigabytes) and execute in a reasonable amount of time (a few hours)

  • The new feature must be thoroughly tested (it should not decrease code coverage)

  • The new feature may not introduce a new dependency

Special cases:

  • A downloader for a new atlas: we are currently being very lenient for this: if the atlas is published and can be used in an example, we will accept the pull request (but see below for specifics).

  • A downloader for a new dataset: the larger the dataset is, the less likely we are to consider including it. Datasets are meant to demo and teach features, rather than be the basis of research.

How to contribute a feature

To contribute a feature, first create an issue, in order to discuss whether the feature can be included or not, and the specifications of this feature. Once agreed on the feature, send us a pull request.

There are specific guidelines about how to write code for the project. They can be found in the contributors guide, below.

Special case: How to contribute an atlas

We want atlases in nilearn to be internally consistent. Specifically, your atlas object should have three attributes (as with the existing atlases):

  • description (bytes): A text description of the atlas. This should be brief but thorough, describing the source (paper), relevant information related to its construction (modality, dataset, method), and if there are more than one maps, a description of each map.

  • labels (list): a list of string labels corresponding to each atlas label, in the same (numerical) order as the atlas labels

  • maps (list or string): the path to the nifti image, or a list of paths

In addition, the atlas will need to be called by a fetcher. For example, see here.

Finally, as with other features, please provide a test for your atlas. Examples can be found here

Who makes decisions

We strongly aim to be a community oriented project where decisions are made based on consensus according to the criteria described above. Decisions are made public, through discussion on issues and pull requests in Github.

The decisions are made by the core-contributors, ie people with write access to the repository, as listed here

If there are open questions, final decisions are made by the Temporary Benevolent Dictator, currently Gaël Varoquaux.

How to contribute to nilearn

This project is a community effort, and everyone is welcome to contribute.

The project is hosted on

The best way to contribute and to help the project is to start working on known issues. See Good first issues to get started.

If an issue does not already exist for a potential contribution, we ask that you first open an issue before sending a Pull Requests.

Opening an issue

Nilearn uses issues for tracking bugs, requesting potential features, and holding project discussions.

Core developers can assign labels on issues, such as:

  • Discussion These issues discuss ongoing discussions on the project where community feedback is requested.

  • Enhancement These issues discuss potential enhancements or additions to the project.

  • Bug These issues detail known bugs in the Nilearn code base.

Pull Requests

We welcome pull requests from all community members. We follow the same conventions as scikit-learn. You can find the recommended process to submit code in the scikit-learn guide to contributing code.

Retrieving the latest code

We use Git for version control and GitHub for hosting our main repository. If you are new on GitHub and don’t know how to work with it, please first have a look at this to get the basics.

You can check out the latest sources with the command:

git clone git://

or if you have write privileges:

git clone

Coding guidelines

Nilearn follows the coding conventions used by scikit-learn. Please read them before you start implementing your changes.

Contributing to the documentation

To build our documentation, we are using sphinx for the main documentation and sphinx-gallery for the example tutorials. If you want to make changes to the example tutorials, please do the following :

  1. First, ensure that you have installed sphinx and sphinx-gallery. You can install the requirements using nilearn/requirements-build-docs.txt.

  2. Fork the Nilearn repository and clone your fork.

  3. Then go to nilearn/examples

  4. Make your changes using reStructuredText files

  5. You can now go to nilearn/doc and build the examples locally:

    make html-strict

    or, if you do not have make install (for instance under Windows):

    python3 -m sphinx -b html -d _build/doctrees . _build/html
  6. Visually review the output in nilearn/doc/_build/html/auto_examples/. If all looks well and there were no errors, commit and push the changes.

  7. You can now open a Pull Request from Nilearn’s Pull Request page.

For more details about the Fork Clone Push worksflow, read here <>_

TIPS : To reduce building time, we suggest you to use the filename_pattern to build just one specific file:

python3 -m sphinx -D -b html -d _build/doctrees . _build/html