Napari

0.7.0 · active · verified Fri Apr 17

napari is an n-dimensional array viewer in Python, providing an interactive, multi-dimensional data viewer for scientific visualization. It emphasizes image processing and analysis, offering a flexible, plugin-friendly architecture. As of version 0.7.0, it continues active development with regular feature additions and improvements to its core architecture and ecosystem.

Common errors

```
ModuleNotFoundError: No module named 'PyQt5'
```
cause A required Qt GUI backend (like PyQt5) is not installed alongside napari.

fix Install napari with a backend using `pip install napari[all]` (recommended) or specify a backend like `pip install napari[pyside6]`.
```
AttributeError: 'NoneType' object has no attribute 'processEvents'
```
cause The napari GUI event loop was not started, or closed prematurely, leading to an attempt to interact with a non-existent GUI context.

fix Ensure `napari.run()` is called, typically within an `if __name__ == '__main__':` block, to start and manage the GUI event loop.
```
TypeError: Viewer.__init__() got an unexpected keyword argument 'title'
```
cause Attempting to pass `title` (or `ndisplay`) directly to the `napari.Viewer` constructor, which was removed in version 0.6.0.

fix Initialize the viewer without `title`/`ndisplay` arguments, then set them as `viewer.window.title = 'My Title'` and `viewer.dims.ndisplay = 3`.
```
DeprecationWarning: napari.app is deprecated and will be removed in a future release.
```
cause Using the deprecated `napari.app.run()` function from older versions.

fix Change `napari.app.run()` to `napari.run()`.

Warnings

breaking Starting with napari 0.7.0, a Qt GUI backend (e.g., PyQt5, PyQt6, PySide2, PySide6) is a mandatory dependency. You must explicitly install one, or use a bundled install like `pip install napari[all]` (which installs PyQt5).
Fix: Ensure you have a Qt backend installed: `pip install napari[all]` or `pip install napari[pyside6]` for a specific backend.
breaking The `Viewer` constructor no longer accepts `title` or `ndisplay` arguments directly. These attributes have moved to `viewer.window.title` and `viewer.dims.ndisplay` respectively.
Fix: Instead of `viewer = napari.Viewer(title='My Viewer')`, use `viewer = napari.Viewer(); viewer.window.title = 'My Viewer'`.
gotcha The napari viewer will not display or be interactive without starting its event loop. This is typically done with `napari.run()` when the script is executed as the main program.
Fix: Always include `if __name__ == '__main__': napari.run()` at the end of your script when running napari directly.
deprecated The `napari.app.run()` function was removed. Use `napari.run()` instead.
Fix: Update calls from `napari.app.run()` to `napari.run()`.
breaking The Layer API was significantly refactored in version 0.5.0. Direct instantiation of `napari.layers.Image` (and other layer types) for adding to the viewer is discouraged. Instead, use the `viewer.add_image()`, `viewer.add_points()`, etc., methods.
Fix: Replace `viewer.add_layer(napari.layers.Image(data))` with `viewer.add_image(data)`.

Install

pip install napari[all] Recommended (installs PyQt5 backend)
pip install napari[pyside6] Install with a specific backend (e.g., PySide6)

Imports

Viewer
```
import napari; viewer = napari.Viewer()
```
run
wrong:
```
import napari; napari.app.run()
```
correct:
```
import napari; napari.run()
```
`napari.app.run()` was removed in 0.4.17; use `napari.run()` instead.

Quickstart

This quickstart initializes a napari viewer, adds a simple 2D image layer generated with NumPy, and ensures the viewer's event loop is started using `napari.run()` for a responsive GUI. Replace `np.random.rand` with your actual image data.

import napari
import numpy as np

# Create an empty napari viewer
viewer = napari.Viewer()

# Add a 2D image layer with random data
viewer.add_image(np.random.rand(128, 128), name='random image')

# Start the napari event loop (essential for the GUI to appear and be interactive)
if __name__ == '__main__':
    napari.run()

view raw JSON →