Contributing guide

We welcome your contributions! Please see the provided steps below and never hesitate to contact us.

If you are a new user, we recommend checking out the detailed Github Docs.

You can see the general direction for napari development and possible work plans in our current Roadmap.

Setting up a development installation

In order to make changes to napari, you will need to fork the repository. If you are not familiar with git, we recommend reading up on this guide.

1. Clone the forked repository to your local machine and change directories:

   git clone https://github.com/your-username/napari.git
   cd napari
   

2. Set the upstream remote to the base napari repository:

   git remote add upstream https://github.com/napari/napari.git
   

3. If you haven’t already, create a development environment:

   Using conda

   After installing conda, create an environment called napari-env with Python 3.10 and activate it.

   conda create -y -n napari-env -c conda-forge python=3.10
   conda activate napari-env
   

   Using venv

   After installing Python on your machine, create a virtual environment on your terminal and activate it. On Linux and MacOS, you can run

   python -m venv <path-to-env>
   source <path-to-env>/bin/activate
   

   See the venv documentation for instructions on Windows.

   Note

   It is highly recommended to create a fresh environment when working with napari, to prevent issues with outdated or conflicting packages in your development environment.

4. Install the package in editable mode, along with all of the developer tools.

   If you only want to use napari, you can install it on most macOS, Linux and Windows systems with Python 3.8-3.10 by following the directions on the instructions page.

   napari supports different Qt backends, and you can choose which one to install and use.

   For example, for PyQt5, the default, you would use the following:

   pip install -e ".[pyqt,dev]"  # (quotes only needed for zsh shell)
   

   If you want to use PySide2 instead, you would use:

   pip install -e ".[pyside,dev]"  # (quotes only needed for zsh shell)
   

   Finally, if you already have a Qt backend installed or want to use an experimental one like Qt6 use:

   pip install -e ".[dev]"  # (quotes only needed for zsh shell)
   

   Note that in this last case you will need to install your Qt backend separately.

5. We use pre-commit to format code with black and lint with ruff automatically prior to each commit. To minimize test errors when submitting pull requests, please install pre-commit in your environment as follows:

   pre-commit install
   

   Upon committing, your code will be formatted according to our black configuration, which includes the settings skip-string-normalization = true and max-line-length = 79. To learn more, see black’s documentation.

   Code will also be linted to enforce the stylistic and logistical rules specified in our flake8 configuration, which currently ignores E203, E501, W503 and C901. For information on any specific flake8 error code, see the Flake8 Rules. You may also wish to refer to the PEP 8 style guide.

   If you wish to tell the linter to ignore a specific line use the # noqa comment along with the specific error code (e.g. import sys  # noqa: E402) but please do not ignore errors lightly.

Now you are all set to start developing with napari.

Contributing documentation

If you wish to contribute documentation changes to napari, please read the guide on contributing documentation.

Adding examples to the Gallery

All of the examples in the examples Gallery are Python scripts that live under the examples folder of the napari repository. Because of how this gallery is built, every such Python script needs a docstring containing at least a title (following the .rst format of docstrings in Python) and one or more tags. This ensures the example will be shown in the correct place in the table of contents for the gallery (see, for example, the Tags page.)

Here’s an example of what that means. The example file add_image.py contains the following:

"""
Add image
=========

Display one image using the :func:`view_image` API.

.. tags:: visualization-basic
"""

from skimage import data
import napari

# create the viewer with an image
viewer = napari.view_image(data.astronaut(), rgb=True)

if __name__ == '__main__':
    napari.run()

The equals signs under “Add image” mark this as the example title. The text below is a short description of the example, and the tags are assigned by the use of the .. tags:: directive. In this case, the only tag associated with this example is visualization-basic. Multiple tags can be separated with a comma.

Note that the examples are .py source files, and any outputs and images will be autogenerated when the documentation site is built.

Note

If you are running any of these examples in an interactive environment (e.g. a Jupyter notebook or IPython console), the block

if __name__ == '__main__':
    napari.run()

is not necessary—you can copy-paste the code above it. However, it is required when running examples as scripts, using for example python add_image.py. Because our example gallery is built from Python scripts, you need to ensure this block is present in all contributed examples.

Adding icons

If you want to add a new icon to the app, make the icon in whatever program you like and add it to napari/resources/icons/. Icons must be in .svg format.

Icons are automatically built into a Qt resource file that is imported when napari is run. If you have changed the icons and would like to force a rebuild of the resources, then you can either delete the autogenerated napari/resources/_qt_resources*.py file, or you can set the NAPARI_REBUILD_RESOURCES environmental variable to a truthy value, for example:

export NAPARI_REBUILD_RESOURCES=1

Icons are typically used inside of one of our stylesheet.qss files, with the {{ id }} variable used to expand the current theme name.

QtDeleteButton {
   image: url("theme_{{ id }}:/delete.svg");
}

Creating and testing themes

A theme is a set of colors used throughout napari. See, for example, the builtin themes in napari/utils/theme.py. To make a new theme, create a new dict with the same keys as one of the existing themes, and replace the values with your new colors. For example

from napari.utils.theme import get_theme, register_theme


blue_theme = get_theme('dark')
blue_theme.update(
    background='rgb(28, 31, 48)',
    foreground='rgb(45, 52, 71)',
    primary='rgb(80, 88, 108)',
    current='rgb(184, 112, 0)',
)

register_theme('blue', blue_theme)

To test out the theme, use the qt_theme_sample.py file from the command line as follows:

python -m napari._qt.widgets.qt_theme_sample

note: you may specify a theme with one additional argument on the command line:

python -m napari._qt.widgets.qt_theme_sample dark

(providing no arguments will show all themes in theme.py)

Translations

Starting with version 0.4.7, napari codebase include internationalization (i18n) and now offers the possibility of installing language packs, which provide localization (l10n) enabling the user interface to be displayed in different languages.

To learn more about the current languages that are in the process of translation, visit the language packs repository

To make your code translatable (localizable), please use the trans helper provided by the napari utilities.

from napari.utils.translations import trans

some_string = trans._("Localizable string")

To learn more, please see the translations guide.

Making changes

Create a new feature branch:

git checkout main -b your-branch-name

git will automatically detect changes to a repository. You can view them with:

git status

Add and commit your changed files:

git add my-file-or-directory
git commit -m "my message"

Tests

We use unit tests, integration tests, and functional tests to ensure that napari works as intended. Writing tests for new code is a critical part of keeping napari maintainable as it grows.

We have dedicated documentation on testing that we recommend you read as you’re working on your first contribution.

Help us make sure it’s you

Each commit you make must have a GitHub-registered email as the author. You can read more here.

To set it, use git config --global user.email your-address@example.com.

Keeping your branches up-to-date

Switch to the main branch:

git checkout main

Fetch changes and update main:

git pull upstream main --tags

This is shorthand for:

git fetch upstream main --tags
git merge upstream/main

Update your other branches:

git checkout your-branch-name
git merge main

Sharing your changes

Update your remote branch:

git push -u origin your-branch-name

You can then make a pull-request to napari’s main branch.

Code of Conduct

napari has a Code of Conduct that should be honored by everyone who participates in the napari community.

Questions, comments, and feedback

If you have questions, comments, suggestions for improvement, or any other inquiries regarding the project, feel free to open an issue.

Issues and pull-requests are written in Markdown. You can find a comprehensive guide here.