How to launch napari#

This tutorial assumes you have already installed napari. For help with installation see our installation tutorial.

This tutorial will teach you all the different ways to launch napari. At the end of the tutorial you should be able to launch napari and see the viewer your favorite way.

Launching `napari`#

There are four ways to launch the napari viewer:

command line
python script
IPython console
jupyter notebook

All four of these methods will launch the same napari viewer but depending on your use-case different ones may be preferable.

Command line usage#

To launch napari from the command line simply run

napari

This command will launch an empty viewer:

image: an empty napari viewer

Once you have the viewer open you can add images through the File -> Open dropdown menu or by dragging and dropping images directly on the viewer. We currently only support files that can be read with skimage.io.imread, such as tif, png, and jpg. We plan on adding support for more exotic file types shortly - see issue #379 for discussion. Finally, you can use the File -> New Image from Clipboard menu item to make a new Image layer from an image (or URL to an image) copied to your Clipboard (keybinding Command/Ctrl+N).

You can also directly load an image into the viewer from the command line by passing the path to the image as an argument as follows

napari my_image.png

If the image is RGB or RGBA use the -r or --rgb flag.

image: napari viewer displaying an image layer

Launching napari directly from the command line is the simplest and fastest way to open the viewer, but it doesn’t allow you to preprocess your images before opening them. It is also currently not possible to save images or other layer types directly from the viewer, but we’ll be adding support for this functionality soon as discussed in #379.

If you wish to interact with your open viewer programmatically you can open an IPython console via Window > console or clicking the ‘Show/Hide IPython console’ button within the viewer buttons.

Python script usage#

To launch napari from a python script, inside your script you can import napari, then create a Viewer and Image layer by adding some image data, using imshow. The Viewer is representative of the napari viewer GUI you launch and stores all the data you add to napari. The Image will store information about the image data you added.

For example, to add an image and print the shape of the image layer data, you can use:

# import sample data
from skimage.data import cells3d

import napari

# create a `Viewer` and `Image` layer here
viewer, image_layer = napari.imshow(cells3d())

# print shape of image datas
print(image_layer.data.shape)

# start the event loop and show the viewer
napari.run()

Note that imshow is a convenience function that is equivalent to:

# import sample data
from skimage.data import cells3d

import napari

viewer = napari.Viewer()
image_layer = viewer.add_image(cells3d())

You can now run your script from the command line to launch the viewer with your data:

python my_example_script.py

The examples gallery consists of code examples which can be downloaded as .py (and .ipynb files) and run as above.

image: napari launched from a python script

An advantage of launching napari from a python script is that you can preprocess your images and add multiple layers before displaying the viewer.

As above, if you wish to interact with your open viewer programmatically you can open an IPython console via Window > console or clicking the ‘Show/Hide IPython console’ button within the viewer buttons.

IPython console usage#

To launch napari from an IPython console import napari and create a Viewer and Image object.

# import sample data
from skimage.data import cells3d

import napari

# create a `Viewer` and `Image` layer here
viewer, image_layer = napari.imshow(cells3d())

napari will automatically use the interactive %gui qt event loop from IPython

image: napari launched from ipython

An advantage of launching napari from an IPython console is that the you can continue to programmatically interact with the viewer from the IPython console, including bidirectional communication, where code run in the console will update the current viewer and where data changed in the GUI will be accessible in the console.

Jupyter notebook usage#

You can also launch napari from a Jupyter notebook. The examples gallery, as mentioned above, can also be downloaded as .ipynb which can be run from a Jupyter notebook.

Below, we launch the notebook example from a Jupyter notebook.

image: napari launched from a Jupyter notebook

Similar to launching from the IPython console, an advantage of launching napari from a Jupyter notebook is that you can continue to programmatically interact with the viewer from Jupyter notebook, including bidirectional communication, where code run in the notebook will update the current viewer and where data changed in the GUI will be accessible in the notebook.

Next steps#

To learn more about:

how to use the napari viewer graphical user interface (GUI), checkout the viewer tutorial
how to use the napari viewer with different types of napari layers, see layers at a glance

Solving common problems#

napari does not launch with `No Qt bindings could be found`#

If you try to start napari and see an error message containing following (or similar) text:

ImportError: No Qt bindings could be found

First you need to validate if you have Qt bindings installed. You can do this by running:

pip list

And check if PyQt5, PySide2, PyQt6 or PySide6 are mentioned in the output as installed.

If there is no such entry, please install one of them following the instructions in Choosing a different Qt backend

If some backend is installed but napari still does not start, please try to start it from command line:

LD_LIBRARY_PATH="" napari

If napari is successfully launched after this command, it means that on your machine the LD_LIBRARY_PATH environment variable is set to a directory that contains a Qt dynamic dependency that is incompatible with the one that napari uses. As linkers first search in LD_LIBRARY_PATH directories, this may cause napari to crash.

If you want to debug this issue for your specific use case, you should start with manually importing the qt package in Python. This will provide you with more information about problem.

Such import may look like one of the following lines:

from PyQt5 import QtWidgets
from PyQt6 import QtWidgets
from PySide2 import QtWidgets
from PySide6 import QtWidgets

Such import may raise an error like:

ImportError: .../site-packages/PyQt5/QtWidgets.abi3.so: undefined symbol: _ZdlPvm, version Qt_5

Then when you identify which file is causing the problem you can use ldd command to check which libraries are used by this file:

ldd .../site-packages/PyQt5/QtWidgets.abi3.so