Preferences#

napari settings#

napari provides persistent settings that are stored on a per environment basis. This means that if you have multiple Python environments, each with a napari installation (e.g. different versions), the napari in each environment will have its own set of stored preferences. So, for example, you could have an environment where napari always uses the Light theme and another one where napari always uses the Dark theme.

A wide range of settings are available, organized into sections, and described in more detail below.

Where settings are stored#

Settings are stored in a settings.yaml file and napari uses appdirs to determine the save location: the platform-specific user configuration directory. You can check where a napari installation has stored settings by looking for “Settings path” in the output of:

napari --info

Resetting settings to defaults using the command line (CLI)#

Sometimes, for example due to a version change, an issue with the stored settings can prevent napari from launching or cause other issues. In those cases, it can be useful to reset the settings to the defaults from the command line. To reset all napari settings to the default values:

napari --reset

Programmatic access to the settings#

Settings are managed by getting the global settings object and modifying settings:

from napari.settings import get_settings

settings = get_settings()
# then modify... e.g:
settings.appearance.theme = 'dark'

You can get more information about individual settings, their types, and default values in each of the settings section descriptions below.

The Preferences dialog#

napari provides a Preferences dialog to manage the settings using a graphical user interface (GUI). Importantly, this dialog also allows you to customize napari keyboard shortcuts (keybindings).

On Windows and Linux, the Preferences dialog can be accessed in the File menu. On macOS, it can be accessed in the napari menu.

The settings are grouped by sections that are accessible in a list on the left side of the dialog.

Application Settings#

Main application settings.

application

More details on the individual Application settings

Brush size on mouse move modifiers

Modifiers to activate changing the brush size by moving the mouse.

  • Access programmatically with SETTINGS.application.brush_size_on_mouse_move_modifiers.

  • Environmental variable: NAPARI_APPLICATION_BRUSH_SIZE_ON_MOUSE_MOVE_MODIFIERS

  • Type: BrushSizeOnMouseModifiers

  • Default: <BrushSizeOnMouseModifiers.ALT: 'Alt'>.

Confirm window or application closing

Ask for confirmation before closing a napari window or application (all napari windows).

  • Access programmatically with SETTINGS.application.confirm_close_window.

  • Environmental variable: NAPARI_APPLICATION_CONFIRM_CLOSE_WINDOW

  • Type: bool

  • Default: True.

Console notification level

Select the notification level for the console.

  • Access programmatically with SETTINGS.application.console_notification_level.

  • Environmental variable: NAPARI_APPLICATION_CONSOLE_NOTIFICATION_LEVEL

  • Type: NotificationSeverity

  • Default: <NotificationSeverity.NONE: 'none'>.

Dask cache

Settings for dask cache (does not work with distributed arrays)

  • Access programmatically with SETTINGS.application.dask.

  • Environmental variable: NAPARI_APPLICATION_DASK

  • Type: DaskSettings

  • Default: DaskSettings(enabled=True, cache=4.193144832).

Depth Axis Orientation

Orientation of the depth axis in 3D view. Default is “Towards”; <0.6.0 was “Away”.

  • Access programmatically with SETTINGS.application.depth_axis_orientation.

  • Environmental variable: NAPARI_APPLICATION_DEPTH_AXIS_ORIENTATION

  • Type: DepthAxisOrientation

  • Default: <DepthAxisOrientation.TOWARDS: 'towards'>.

Grid Height

Number of rows in the grid.

  • Access programmatically with SETTINGS.application.grid_height.

  • Environmental variable: NAPARI_APPLICATION_GRID_HEIGHT

  • Type: ConstrainedIntValue

  • Default: -1.

Grid Spacing

The amount of spacing inbetween grid viewboxes. If between 0 and 1, it is interpreted as a proportion of the size of the viewboxes. If equal or greater than 1, it is interpreted as screen pixels.

  • Access programmatically with SETTINGS.application.grid_spacing.

  • Environmental variable: NAPARI_APPLICATION_GRID_SPACING

  • Type: ConstrainedFloatValue

  • Default: 0.

Grid Stride

Number of layers to place in each grid viewbox before moving on to the next viewbox. A negative stride will cause the order in which the layers are placed in the grid to be reversed. 0 is not a valid entry.

  • Access programmatically with SETTINGS.application.grid_stride.

  • Environmental variable: NAPARI_APPLICATION_GRID_STRIDE

  • Type: ConstrainedIntValue

  • Default: 1.

Grid Width

Number of columns in the grid.

  • Access programmatically with SETTINGS.application.grid_width.

  • Environmental variable: NAPARI_APPLICATION_GRID_WIDTH

  • Type: ConstrainedIntValue

  • Default: -1.

GUI notification level

Select the notification level for the user interface.

  • Access programmatically with SETTINGS.application.gui_notification_level.

  • Environmental variable: NAPARI_APPLICATION_GUI_NOTIFICATION_LEVEL

  • Type: NotificationSeverity

  • Default: <NotificationSeverity.INFO: 'info'>.

Delay to treat button as hold in seconds

This affects certain actions where a short press and a long press have different behaviors, such as changing the mode of a layer permanently or only during the long press.

  • Access programmatically with SETTINGS.application.hold_button_delay.

  • Environmental variable: NAPARI_APPLICATION_HOLD_BUTTON_DELAY

  • Type: float

  • Default: 0.5.

Horizontal Axis Orientation

Orientation of the horizontal axis in 2D and 3D view. Default is “Right”.

  • Access programmatically with SETTINGS.application.horizontal_axis_orientation.

  • Environmental variable: NAPARI_APPLICATION_HORIZONTAL_AXIS_ORIENTATION

  • Type: HorizontalAxisOrientation

  • Default: <HorizontalAxisOrientation.RIGHT: 'right'>.

Language

Select the display language for the user interface.

  • Access programmatically with SETTINGS.application.language.

  • Environmental variable: NAPARI_APPLICATION_LANGUAGE

  • Type: Language

  • Default: 'en'.

New labels data type

data type for labels layers created with the “new labels” button.

  • Access programmatically with SETTINGS.application.new_labels_dtype.

  • Environmental variable: NAPARI_APPLICATION_NEW_LABELS_DTYPE

  • Type: LabelDTypes

  • Default: <LabelDTypes.uint8: 'uint8'>.

Playback frames per second

Playback speed in frames per second.

  • Access programmatically with SETTINGS.application.playback_fps.

  • Environmental variable: NAPARI_APPLICATION_PLAYBACK_FPS

  • Type: int

  • Default: 10.

Playback loop mode

Loop mode for playback.

  • Access programmatically with SETTINGS.application.playback_mode.

  • Environmental variable: NAPARI_APPLICATION_PLAYBACK_MODE

  • Type: LoopMode

  • Default: <LoopMode.LOOP: 'loop'>.

Save window geometry

Toggle saving the main window size and position.

  • Access programmatically with SETTINGS.application.save_window_geometry.

  • Environmental variable: NAPARI_APPLICATION_SAVE_WINDOW_GEOMETRY

  • Type: bool

  • Default: True.

Save window state

Toggle saving the main window state of widgets.

  • Access programmatically with SETTINGS.application.save_window_state.

  • Environmental variable: NAPARI_APPLICATION_SAVE_WINDOW_STATE

  • Type: bool

  • Default: False.

Full path to a startup script

Path to a Python script that will be executed on napari startup. This can be used to customize the behavior of napari or load specific plugins automatically.

  • Access programmatically with SETTINGS.application.startup_script.

  • Environmental variable: NAPARI_APPLICATION_STARTUP_SCRIPT

  • Type: Path

  • Default: PosixPath('.').

Vertical Axis Orientation

Orientation of the vertical axis in 2D and 3D view. Default is “Down”.

  • Access programmatically with SETTINGS.application.vertical_axis_orientation.

  • Environmental variable: NAPARI_APPLICATION_VERTICAL_AXIS_ORIENTATION

  • Type: VerticalAxisOrientation

  • Default: <VerticalAxisOrientation.DOWN: 'down'>.

Appearance Settings#

User interface appearance settings.

appearance

More details on the individual Appearance settings

Font size

Select the user interface font size.

  • Access programmatically with SETTINGS.appearance.font_size.

  • Environmental variable: NAPARI_APPEARANCE_FONT_SIZE

  • Type: ConstrainedIntValue

  • Default: 9.

Highlight

Select the highlight color and thickness to use when hovering over shapes/points.

  • Access programmatically with SETTINGS.appearance.highlight.

  • Environmental variable: NAPARI_APPEARANCE_HIGHLIGHT

  • Type: HighlightSettings

  • Default: HighlightSettings(highlight_thickness=1, highlight_color=[0.0, 0.6, 1.0, 1.0]).

Show layer tooltips

Toggle to display a tooltip on mouse hover.

  • Access programmatically with SETTINGS.appearance.layer_tooltip_visibility.

  • Environmental variable: NAPARI_APPEARANCE_LAYER_TOOLTIP_VISIBILITY

  • Type: bool

  • Default: False.

Theme

Select the user interface theme.

  • Access programmatically with SETTINGS.appearance.theme.

  • Environmental variable: NAPARI_APPEARANCE_THEME

  • Type: Theme

  • Default: 'dark'.

Update status based on layer

Calculate status bar based on current active layer and mouse position.

  • Access programmatically with SETTINGS.appearance.update_status_based_on_layer.

  • Environmental variable: NAPARI_APPEARANCE_UPDATE_STATUS_BASED_ON_LAYER

  • Type: bool

  • Default: True.

Plugins Settings#

Plugins settings.

plugins

More details on the individual Plugins settings

Plugin sort order

Sort plugins for each action in the order to be called.

  • Access programmatically with SETTINGS.plugins.call_order.

  • Environmental variable: NAPARI_PLUGINS_CALL_ORDER

  • Type: Mapping[str, list[napari.settings._plugins.PluginHookOption]]

  • Default: {}.

File extension readers

Assign file extensions to specific reader plugins

  • Access programmatically with SETTINGS.plugins.extension2reader.

  • Environmental variable: NAPARI_PLUGINS_EXTENSION2READER

  • Type: Mapping[str, str]

  • Default: {}.

Only warn for new adapted plugins

Only warn about newly installed adapted plugins. Leave unchecked to receive warning with each startup.

  • Access programmatically with SETTINGS.plugins.only_new_shimmed_plugins_warning.

  • Environmental variable: NAPARI_PLUGINS_ONLY_NEW_SHIMMED_PLUGINS_WARNING

  • Type: bool

  • Default: False.

Use npe2 adaptor

Use npe2-adaptor for first generation plugins. When an npe1 plugin is found, this option will import its contributions and create/cache a ‘shim’ npe2 manifest that allows it to be treated like an npe2 plugin (with delayed imports, etc…)

  • Access programmatically with SETTINGS.plugins.use_npe2_adaptor.

  • Environmental variable: NAPARI_PLUGINS_USE_NPE2_ADAPTOR

  • Type: bool

  • Default: True.

Shortcuts Settings#

Shortcut settings.

shortcuts

More details on the individual Shortcuts settings

shortcuts

Set keyboard shortcuts for actions.

  • Access programmatically with SETTINGS.shortcuts.shortcuts.

  • Environmental variable: NAPARI_SHORTCUTS_SHORTCUTS

  • Type: Mapping[str, list[app_model.types._keys._keybindings.KeyBinding]]

Default Shortcuts

Action

Shortcut

napari:toggle_console_visibility

[<KeyBinding at 0x7ff2ccf4d100: Ctrl+Shift+C>]

napari:toggle_ndisplay

[<KeyBinding at 0x7ff2ccf4d340: Ctrl+Y>]

napari:toggle_theme

[<KeyBinding at 0x7ff2ccf4d040: Ctrl+Shift+T>]

napari:reset_view

[<KeyBinding at 0x7ff2ccf4ce00: Ctrl+R>]

napari:delete_selected_layers

[<KeyBinding at 0x7ff2ccf4ce60: Ctrl+Delete>, <KeyBinding at 0x7ff2ccf4cce0: Ctrl+Backspace>]

napari:show_shortcuts

[<KeyBinding at 0x7ff2ccf4cd40: Ctrl+Alt+/>]

napari:increment_dims_left

[<KeyBinding at 0x7ff2ccf4cbc0: Left>]

napari:increment_dims_right

[<KeyBinding at 0x7ff2ccf4cc20: Right>]

napari:focus_axes_up

[<KeyBinding at 0x7ff2ccf4c1a0: Alt+Up>]

napari:focus_axes_down

[<KeyBinding at 0x7ff2ccf4cb30: Alt+Down>]

napari:roll_axes

[<KeyBinding at 0x7ff2ccf4c230: Ctrl+E>]

napari:transpose_axes

[<KeyBinding at 0x7ff2ccf4c140: Ctrl+T>]

napari:rotate_layers

[<KeyBinding at 0x7ff2ccf4c5f0: Ctrl+Alt+T>]

napari:toggle_grid

[<KeyBinding at 0x7ff2ccf4c260: Ctrl+G>]

napari:toggle_selected_visibility

[<KeyBinding at 0x7ff2ccf4c350: V>]

napari:toggle_unselected_visibility

[<KeyBinding at 0x7ff2ccf4c3b0: Shift+V>]

napari:select_layer_above

[<KeyBinding at 0x7ff2ccf4c620: Ctrl+Up>]

napari:select_layer_below

[<KeyBinding at 0x7ff2ccf4c4d0: Ctrl+Down>]

napari:show_only_layer_above

[<KeyBinding at 0x7ff2ccf4c830: Shift+Alt+Up>]

napari:show_only_layer_below

[<KeyBinding at 0x7ff2ccf4c5c0: Shift+Alt+Down>]

napari:hold_for_pan_zoom

[<KeyBinding at 0x7ff2ccf4c860: Space>]

napari:activate_labels_erase_mode

[<KeyBinding at 0x7ff2ccf4c710: 1>, <KeyBinding at 0x7ff2ccf4c8f0: E>]

napari:activate_labels_paint_mode

[<KeyBinding at 0x7ff2ccf4c800: 2>, <KeyBinding at 0x7ff2ccf4ca10: P>]

napari:activate_labels_polygon_mode

[<KeyBinding at 0x7ff2ccf4c7d0: 3>]

napari:activate_labels_fill_mode

[<KeyBinding at 0x7ff2ccf4ca40: 4>, <KeyBinding at 0x7ff2ccf4ca70: F>]

napari:activate_labels_picker_mode

[<KeyBinding at 0x7ff2ce3ee2a0: 5>, <KeyBinding at 0x7ff2ce3ed970: L>]

napari:activate_labels_pan_zoom_mode

[<KeyBinding at 0x7ff2ced8ce60: 6>, <KeyBinding at 0x7ff2cf2817c0: Z>]

napari:activate_labels_transform_mode

[<KeyBinding at 0x7ff2d27e5b50: 7>]

napari:new_label

[<KeyBinding at 0x7ff2d1feac90: M>]

napari:swap_selected_and_background_labels

[<KeyBinding at 0x7ff2d1febd70: X>]

napari:decrease_label_id

[<KeyBinding at 0x7ff2d2493c20: ->]

napari:increase_label_id

[<KeyBinding at 0x7ff2d2491100: =>]

napari:decrease_brush_size

[<KeyBinding at 0x7ff2d24921b0: [>]

napari:increase_brush_size

[<KeyBinding at 0x7ff2d24930e0: ]>]

napari:toggle_preserve_labels

[<KeyBinding at 0x7ff2d2493710: B>]

napari:reset_polygon

[<KeyBinding at 0x7ff2d2491fd0: Escape>]

napari:complete_polygon

[<KeyBinding at 0x7ff2d2492c90: Enter>]

napari:activate_points_add_mode

[<KeyBinding at 0x7ff2d2492600: 2>, <KeyBinding at 0x7ff2d24914c0: P>]

napari:activate_points_select_mode

[<KeyBinding at 0x7ff2d2492390: 3>, <KeyBinding at 0x7ff2d2491c10: S>]

napari:activate_points_pan_zoom_mode

[<KeyBinding at 0x7ff2d24903e0: 4>, <KeyBinding at 0x7ff2d24912e0: Z>]

napari:activate_points_transform_mode

[<KeyBinding at 0x7ff2d2490d40: 5>]

napari:select_all_in_slice

[<KeyBinding at 0x7ff2d2490290: A>, <KeyBinding at 0x7ff2d2490590: Ctrl+A>]

napari:select_all_data

[<KeyBinding at 0x7ff2d2493a40: Shift+A>]

napari:delete_selected_points

[<KeyBinding at 0x7ff2d278aa50: 1>, <KeyBinding at 0x7ff2d24bbcb0: Delete>, <KeyBinding at 0x7ff2d24bae10: Backspace>]

napari:activate_add_rectangle_mode

[<KeyBinding at 0x7ff2d24ba420: R>]

napari:activate_add_ellipse_mode

[<KeyBinding at 0x7ff2d24b9910: E>]

napari:activate_add_line_mode

[<KeyBinding at 0x7ff2d24b8a70: L>]

napari:activate_add_path_mode

[<KeyBinding at 0x7ff2d24b8230: T>]

napari:activate_add_polyline_mode

[<KeyBinding at 0x7ff2d24b8080: Shift+L>]

napari:activate_add_polygon_mode

[<KeyBinding at 0x7ff2d24b8710: P>]

napari:activate_add_polygon_lasso_mode

[<KeyBinding at 0x7ff2d24b9730: Shift+P>]

napari:activate_direct_mode

[<KeyBinding at 0x7ff2d24b8c50: 4>, <KeyBinding at 0x7ff2d24b9550: D>]

napari:activate_select_mode

[<KeyBinding at 0x7ff2d24ba300: 5>, <KeyBinding at 0x7ff2d24b9af0: S>]

napari:activate_shapes_pan_zoom_mode

[<KeyBinding at 0x7ff2d24ba1e0: 6>, <KeyBinding at 0x7ff2d24bac30: Z>]

napari:activate_shapes_transform_mode

[<KeyBinding at 0x7ff2d24ba540: 7>]

napari:activate_vertex_insert_mode

[<KeyBinding at 0x7ff2d24baae0: 2>, <KeyBinding at 0x7ff2d24bbb60: I>]

napari:activate_vertex_remove_mode

[<KeyBinding at 0x7ff2d24baff0: 1>, <KeyBinding at 0x7ff2d24bb7d0: X>]

napari:copy_selected_shapes

[<KeyBinding at 0x7ff2d291ec00: Ctrl+C>]

napari:paste_shape

[<KeyBinding at 0x7ff2d25a4740: Ctrl+V>]

napari:move_shapes_selection_to_front

[<KeyBinding at 0x7ff2d27adbb0: F>]

napari:move_shapes_selection_to_back

[<KeyBinding at 0x7ff2d2444d10: B>]

napari:select_shapes_in_slice

[<KeyBinding at 0x7ff2d24440b0: A>, <KeyBinding at 0x7ff2d2444350: Ctrl+A>]

napari:delete_selected_shapes

[<KeyBinding at 0x7ff2d2444410: 3>, <KeyBinding at 0x7ff2d2444590: Delete>, <KeyBinding at 0x7ff2d2444800: Backspace>]

napari:finish_drawing_shape

[<KeyBinding at 0x7ff2d24449b0: Enter>, <KeyBinding at 0x7ff2d2444aa0: Escape>]

napari:orient_plane_normal_along_x

[<KeyBinding at 0x7ff2d2444b60: X>]

napari:orient_plane_normal_along_y

[<KeyBinding at 0x7ff2d2444c20: Y>]

napari:orient_plane_normal_along_z

[<KeyBinding at 0x7ff2d2445eb0: Z>]

napari:orient_plane_normal_along_view_direction

[<KeyBinding at 0x7ff2d2446ba0: O>]

napari:activate_image_pan_zoom_mode

[<KeyBinding at 0x7ff2d2432480: 1>]

napari:activate_image_transform_mode

[<KeyBinding at 0x7ff2d2430860: 2>]

napari:activate_vectors_pan_zoom_mode

[<KeyBinding at 0x7ff2d24311c0: 1>]

napari:activate_vectors_transform_mode

[<KeyBinding at 0x7ff2d2430e60: 2>]

napari:activate_tracks_pan_zoom_mode

[<KeyBinding at 0x7ff2d24317c0: 1>]

napari:activate_tracks_transform_mode

[<KeyBinding at 0x7ff2d24318e0: 2>]

napari:activate_surface_pan_zoom_mode

[<KeyBinding at 0x7ff2d2431940: 1>]

napari:activate_surface_transform_mode

[<KeyBinding at 0x7ff2d2431af0: 2>]

Experimental Settings#

Experimental settings.

experimental

More details on the individual Experimental settings

Render Images Asynchronously

Asynchronous loading of image data. This setting partially loads data while viewing.

  • Access programmatically with SETTINGS.experimental.async_.

  • Environmental variable: NAPARI_EXPERIMENTAL_ASYNC_

  • Type: bool

  • Default: False.

Enable autoswapping rendering buffers.

Autoswapping rendering buffers improves quality by reducing tearing artifacts, while sacrificing some performance.

  • Access programmatically with SETTINGS.experimental.autoswap_buffers.

  • Environmental variable: NAPARI_EXPERIMENTAL_AUTOSWAP_BUFFERS

  • Type: bool

  • Default: False.

Colormap backend to use for Labels layer

*Color mapping backend to use for Labels layer. ‘partsegcore’ requires the optional ‘partsegcore-compiled-backend’ package. ‘numba’ requires the optional ‘numba’ package. ‘pure python’ uses only NumPy and Python. The ‘fastest available’ backend will select the fastest installed backend. *

  • Access programmatically with SETTINGS.experimental.colormap_backend.

  • Environmental variable: NAPARI_EXPERIMENTAL_COLORMAP_BACKEND

  • Type: ColormapBackend

  • Default: fastest_available.

Double-click Labels polygon completion radius (-1 to always complete)

Max radius in pixels from first vertex for double-click to complete a polygon; set -1 to always complete.

  • Access programmatically with SETTINGS.experimental.completion_radius.

  • Environmental variable: NAPARI_EXPERIMENTAL_COMPLETION_RADIUS

  • Type: int

  • Default: -1.

Minimum distance threshold of shapes lasso and path tool

Value determines how many screen pixels one has to move before another vertex can be added to the polygonor path.

  • Access programmatically with SETTINGS.experimental.lasso_vertex_distance.

  • Environmental variable: NAPARI_EXPERIMENTAL_LASSO_VERTEX_DISTANCE

  • Type: ConstrainedIntValue

  • Default: 10.

Shapes polygon lasso and path RDP epsilon

Setting this higher removes more points from polygons or paths. Setting this to 0 keeps all vertices of a given polygon or path.

  • Access programmatically with SETTINGS.experimental.rdp_epsilon.

  • Environmental variable: NAPARI_EXPERIMENTAL_RDP_EPSILON

  • Type: ConstrainedFloatValue

  • Default: 0.5.

Triangulation backend to use for Shapes layer

*Triangulation backend to use for Shapes layer. The ‘bermuda’ requires the optional ‘bermuda’ package. The ‘partsegcore’ requires the optional ‘partsegcore-compiled-backend’ package. The ‘triangle’ requires the optional ‘triangle’ package. The ‘numba’ backend requires the optional ‘numba’ package. The ‘pure python’ backend uses the default Python triangulation from vispy. The ‘fastest available’ backend will select the fastest available backend. *

  • Access programmatically with SETTINGS.experimental.triangulation_backend.

  • Environmental variable: NAPARI_EXPERIMENTAL_TRIANGULATION_BACKEND

  • Type: TriangulationBackend

  • Default: fastest_available.

Reset settings to defaults using the Preferences dialog#

To reset the preferences click on the Restore defaults button and continue by clicking on Restore Defaults.

Overriding settings#

napari settings can also be overridden by using environment variables. The variable names follow a pattern: they start with NAPARI, followed by the Preference section name, yielding, for example, NAPARI_APPLICATION, followed by the setting name, yielding, for example, NAPARI_APPLICATION_CONFIRM_CLOSE_WINDOW. (This specific setting controls whether napari will prompt you to confirm closing the application.) You can also find the environmentvariable names for each setting in the descriptions for each of the Preference sections above.

You can override settings for a single napari session by setting environment variables at launch:

On Mac and Linux:

NAPARI_APPLICATION_CONFIRM_CLOSE_WINDOW=False napari

On Windows:

set NAPARI_APPLICATION_CONFIRM_CLOSE_WINDOW=False && napari

Or programatically in a script/notebook:

import os
os.environ['NAPARI_APPLICATION_CONFIRM_CLOSE_WINDOW'] = 'False'

Or, depending on your shell, you can persist environment variables for a shell session using the export command (e.g. bash, zsh):

export NAPARI_APPLICATION_CONFIRM_CLOSE_WINDOW=False

Or, to persist between shell sessions, add the above command to your shell configuration file e.g ~/.bashrc or ~/.zshrc.