How to install napari

This guide will teach you how to do a clean install of napari and launch the viewer.

If you’re already familiar with Python, napari can be installed from PyPI or conda-forge using your favorite virtual environment and package manager. Otherwise, keep reading for instructions on how to install napari as a Python package.

Tip

If you just want to get started quickly with napari as an app, check out our napari app installation instructions.

Install as Python package (recommended)

This installation method allows you to use napari from Python to programmatically interact with the app. It is the best way to install napari and make full use of all its features.

Note

If you want to contribute code back into napari, you should follow the development installation instructions in the contributing guide instead.

It requires:

• Python 3.10-3.13

• the ability to install python packages via pip OR conda-forge

You may also want:

• an environment manager like conda or venv (Highly recommended)

Note

New to Python or uncertain about conda, pip, and virtual environments? Here are some resources we recommend:

• Talley Lambert’s “Getting started running Python” slides

• Scientific Python: Getting started with Python for science

• Detailed comparison of Python environment management tools

Python package distributions of napari can be installed via pip, conda-forge, or from source.

Important

While not strictly required, it is highly recommended to install napari into a clean virtual environment using an environment manager like conda or venv.

This should be set up before you install napari. For example, setting with up a Python 3.11 environment with conda:

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

Choose one of the options below to install napari as a Python package.

From conda-forge using conda

If you prefer to manage packages with conda, napari is available on the conda-forge channel. We also recommend this path for users of arm64 macOS machines (Apple Silicon, meaning a processor with a name like “M1”). You can install it with:

conda install -c conda-forge napari pyqt

You can then upgrade to a new version of napari using:

conda update napari

If you want to install napari with PySide2 as the backend you need to install it using

conda install -c conda-forge napari pyside2

Note

In some cases, conda’s default solver can struggle to find out which packages need to be installed for napari. If it takes too long or you get the wrong version of napari (see below), consider:

1. Overriding your default channels to use only conda-forge by adding --override-channels and specifying the napari and Python versions explicitly. For example, use python=3.11 to get Python 3.11 and napari=0.6.5 to specify the napari version as 0.6.5, the current release.

2. Switching to the new, faster libmamba solver, by updating your conda (libmamba is the default solver from conda 23.10 onwards):

conda update -n base conda

From PyPI using pip

napari can be installed from PyPI on most macOS, Linux, and Windows systems with Python 3.10-3.13 using pip:

python -m pip install "napari[all]"

You can then upgrade napari to a new version using:

python -m pip install "napari[all]" --upgrade

(See Choosing a different Qt backend below for an explanation of the [all] notation.)

(See Using constraints file for help installing older versions of napari)

From the main branch on Github

To install the latest version with yet to be released features from Github you can use pip:

python -m pip install "git+https://github.com/napari/napari.git#egg=napari[all]"

Checking it worked

After installation you should be able to launch napari from the command line by simply running

napari

An empty napari viewer should appear as follows:

Note

On some platforms, particularly macOS and Windows, there may be a ~30 second delay before the viewer appears on first launch. This is expected and subsequent launches should be quick. However, anti-malware and other security software measures may further delay launches—even after the first launch.

You can check the napari version, to ensure it’s what you expect, for example the current release 0.6.5, using the command: napari --version .

Advanced installation options

Choosing a different Qt backend

napari needs a library called Qt to run its user interface (UI). In Python, there are two alternative libraries to run this, called PyQt5 and PySide2. By default, we don’t choose for you, and simply running python -m pip install napari will not install either. You might already have one of them installed in your environment, thanks to other scientific packages such as Spyder or matplotlib. If neither is available, running napari will result in an error message asking you to install one of them.

Running python -m pip install "napari[all]" will install the default framework, which is currently PyQt5–but this could change in the future.

To install napari with a specific framework, you can use:

python -m pip install "napari[pyqt6, optional]"    # for PyQt6

# OR
python -m pip install "napari[pyside2, optional]"  # for PySide2

By including optional you will install everything that napari[all] includes, but with the Qt backend of your choice.

Please note that, if you have a Mac with the newer arm64 architecture (Apple Silicon), then installing the PySide2 backend using pip is not supported because pre-compiled PySide2 packages (wheels) are not available on PyPI, the repository used by pip. However, you can install pyside2 separately, for example from conda-forge, and then use pip install napari.

Note

If you switch backends, it’s a good idea to pip uninstall the one you’re not using.

Using constraints files

Since napari 0.4.18, we store constraints files with information about each exact dependency version against which napari was tested. This could be useful if you need to install napari as a package from PyPI, and prevents creating environments where napari does not start or work properly.

The constraints files are stored in the napari repository under resources/constraints/constraints_py3.10.txt. To find constraints for specific releases, go under the link https://github.com/napari/napari/tree/{tag}/resources/constraints replacing {tag} with the desired napari version.

pip install napari[backend_selection] -c path/to/constraints/file

For example, if you would like to install napari with PyQt6 on python 3.10:

pip install napari[pyqt6, optional] -c constraints_py3.10.txt

Next steps

• to start learning how to use napari, checkout our getting started tutorial

• if you are interested in contributing to napari please check our contributing guidelines

• if you are running into issues or bugs, please open a new issue on our issue tracker

• if you want help using napari, we are a community partner on the imagesc forum and all usage support requests should be posted on the forum with the tag napari. We look forward to interacting with you there!