Preferences#

Starting with version 0.4.6, napari provides persistent 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'

Reset to defaults via CLI#

To reset all napari settings to the default values:

napari --reset

The preferences dialog#

Starting with version 0.4.6, napari provides a preferences dialog to manage some of the provided options.

Application#

application

Appearance#

appearance

Plugins#

plugins

Shortcuts#

shortcuts

Experimental#

experimental

Reset to defaults via UI#

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

Sections#

The settings are grouped by sections and napari core provides the following:

APPLICATION#

Main 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.

  • Type: BrushSizeOnMouseModifiers.

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

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: bool.

  • Default: True.

  • UI: This setting can be configured via the preferences dialog.

Console notification level#

Select the notification level for the console.

  • Access programmatically with SETTINGS.application.console_notification_level.

  • Type: NotificationSeverity.

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

  • UI: This setting can be configured via the preferences dialog.

Dask cache#

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

  • Access programmatically with SETTINGS.application.dask.

  • Type: DaskSettings.

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

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: DepthAxisOrientation.

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

  • UI: This setting can be configured via the preferences dialog.

First time#

Indicate if napari is running for the first time. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.first_time.

  • Type: bool.

  • Default: True.

Grid Height#

Number of rows in the grid.

  • Access programmatically with SETTINGS.application.grid_height.

  • Type: ConstrainedIntValue.

  • Default: -1.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: ConstrainedFloatValue.

  • Default: 0.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: ConstrainedIntValue.

  • Default: 1.

  • UI: This setting can be configured via the preferences dialog.

Grid Width#

Number of columns in the grid.

  • Access programmatically with SETTINGS.application.grid_width.

  • Type: ConstrainedIntValue.

  • Default: -1.

  • UI: This setting can be configured via the preferences dialog.

GUI notification level#

Select the notification level for the user interface.

  • Access programmatically with SETTINGS.application.gui_notification_level.

  • Type: NotificationSeverity.

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

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: float.

  • Default: 0.5.

  • UI: This setting can be configured via the preferences dialog.

Horizontal Axis Orientation#

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

  • Access programmatically with SETTINGS.application.horizontal_axis_orientation.

  • Type: HorizontalAxisOrientation.

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

  • UI: This setting can be configured via the preferences dialog.

IPython interactive#

Toggle the use of interactive %gui qt event loop when creating napari Viewers in IPython.

  • Access programmatically with SETTINGS.application.ipy_interactive.

  • Type: bool.

  • Default: True.

Language#

Select the display language for the user interface.

  • Access programmatically with SETTINGS.application.language.

  • Type: Language.

  • Default: 'en'.

  • UI: This setting can be configured via the preferences dialog.

New labels data type#

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

  • Access programmatically with SETTINGS.application.new_labels_dtype.

  • Type: LabelDTypes.

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

  • UI: This setting can be configured via the preferences dialog.

Opened folders history#

Last saved list of opened folders. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.open_history.

  • Type: List[str].

  • Default: [].

Playback frames per second#

Playback speed in frames per second.

  • Access programmatically with SETTINGS.application.playback_fps.

  • Type: int.

  • Default: 10.

  • UI: This setting can be configured via the preferences dialog.

Playback loop mode#

Loop mode for playback.

  • Access programmatically with SETTINGS.application.playback_mode.

  • Type: LoopMode.

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

  • UI: This setting can be configured via the preferences dialog.

Plugin widget positions#

Per-widget last saved position of plugin dock widgets. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.plugin_widget_positions.

  • Type: Mapping[str, str].

  • Default: {}.

Preferences size#

Last saved width and height for the preferences dialog. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.preferences_size.

  • Type: Optional[Tuple[int, int]].

  • Default: None.

Saved folders history#

Last saved list of saved folders. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.save_history.

  • Type: List[str].

  • Default: [].

Save window geometry#

Toggle saving the main window size and position.

  • Access programmatically with SETTINGS.application.save_window_geometry.

  • Type: bool.

  • Default: True.

  • UI: This setting can be configured via the preferences dialog.

Save window state#

Toggle saving the main window state of widgets.

  • Access programmatically with SETTINGS.application.save_window_state.

  • Type: bool.

  • Default: False.

  • UI: This setting can be configured via the preferences dialog.

Vertical Axis Orientation#

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

  • Access programmatically with SETTINGS.application.vertical_axis_orientation.

  • Type: VerticalAxisOrientation.

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

  • UI: This setting can be configured via the preferences dialog.

Window fullscreen#

Last saved fullscreen state for the main window. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.window_fullscreen.

  • Type: bool.

  • Default: False.

Window maximized state#

Last saved maximized state for the main window. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.window_maximized.

  • Type: bool.

  • Default: False.

Window position#

Last saved x and y coordinates for the main window. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.window_position.

  • Type: Optional[Tuple[int, int]].

  • Default: None.

Window size#

Last saved width and height for the main window. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.window_size.

  • Type: Optional[Tuple[int, int]].

  • Default: None.

Window state#

Last saved state of dockwidgets and toolbars for the main window. This setting is managed by the application.

  • Access programmatically with SETTINGS.application.window_state.

  • Type: Optional[str].

  • Default: None.

Show status bar#

Toggle diplaying the status bar for the main window.

  • Access programmatically with SETTINGS.application.window_statusbar.

  • Type: bool.

  • Default: True.

APPEARANCE#

User interface appearance settings.

Font size#

Select the user interface font size.

  • Access programmatically with SETTINGS.appearance.font_size.

  • Type: ConstrainedIntValue.

  • Default: 9.

  • UI: This setting can be configured via the preferences dialog.

Highlight#

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

  • Access programmatically with SETTINGS.appearance.highlight.

  • Type: HighlightSettings.

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

  • UI: This setting can be configured via the preferences dialog.

Show layer tooltips#

Toggle to display a tooltip on mouse hover.

  • Access programmatically with SETTINGS.appearance.layer_tooltip_visibility.

  • Type: bool.

  • Default: False.

  • UI: This setting can be configured via the preferences dialog.

Theme#

Select the user interface theme.

  • Access programmatically with SETTINGS.appearance.theme.

  • Type: Theme.

  • Default: 'dark'.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: bool.

  • Default: True.

  • UI: This setting can be configured via the preferences dialog.

PLUGINS#

Plugins settings.

Shimmed plugins already warned#

Set of installed shimmed plugins that have already been warned about.

  • Access programmatically with SETTINGS.plugins.already_warned_shimmed_plugins.

  • Type: Set[str].

  • Default: set().

Plugin sort order#

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

  • Access programmatically with SETTINGS.plugins.call_order.

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

  • Default: {}.

  • UI: This setting can be configured via the preferences dialog.

Disabled plugins#

Plugins to disable on application start.

  • Access programmatically with SETTINGS.plugins.disabled_plugins.

  • Type: Set[str].

  • Default: set().

File extension readers#

Assign file extensions to specific reader plugins

  • Access programmatically with SETTINGS.plugins.extension2reader.

  • Type: Mapping[str, str].

  • Default: {}.

  • UI: This setting can be configured via the preferences dialog.

Writer plugin extension association.#

Assign file extensions to specific writer plugins

  • Access programmatically with SETTINGS.plugins.extension2writer.

  • 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.

  • Type: bool.

  • Default: False.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: bool.

  • Default: True.

  • UI: This setting can be configured via the preferences dialog.

SHORTCUTS#

Shortcut settings.

shortcuts#

Set keyboard shortcuts for actions.

  • Access programmatically with SETTINGS.shortcuts.shortcuts.

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

  • Default: {'napari:toggle_console_visibility': [<KeyBinding at 0x7fa39b8a03a0: Ctrl+Shift+C>], 'napari:toggle_ndisplay': [<KeyBinding at 0x7fa39b8a0580: Ctrl+Y>], 'napari:toggle_theme': [<KeyBinding at 0x7fa39b8a0b80: Ctrl+Shift+T>], 'napari:reset_view': [<KeyBinding at 0x7fa39b8a0df0: Ctrl+R>], 'napari:delete_selected_layers': [<KeyBinding at 0x7fa39b8a04c0: Ctrl+Delete>, <KeyBinding at 0x7fa39b8a0340: Ctrl+Backspace>], 'napari:show_shortcuts': [<KeyBinding at 0x7fa39b8a00a0: Ctrl+Alt+/>], 'napari:increment_dims_left': [<KeyBinding at 0x7fa39b8a0160: Left>], 'napari:increment_dims_right': [<KeyBinding at 0x7fa39b8a3790: Right>], 'napari:focus_axes_up': [<KeyBinding at 0x7fa39b8a3820: Alt+Up>], 'napari:focus_axes_down': [<KeyBinding at 0x7fa39b8a38b0: Alt+Down>], 'napari:roll_axes': [<KeyBinding at 0x7fa39b8a3940: Ctrl+E>], 'napari:transpose_axes': [<KeyBinding at 0x7fa39b8a39d0: Ctrl+T>], 'napari:rotate_layers': [<KeyBinding at 0x7fa39b8a3a30: Ctrl+Alt+T>], 'napari:toggle_grid': [<KeyBinding at 0x7fa39b8a3a90: Ctrl+G>], 'napari:toggle_selected_visibility': [<KeyBinding at 0x7fa39b8a3b20: V>], 'napari:toggle_unselected_visibility': [<KeyBinding at 0x7fa39b8a3bb0: Shift+V>], 'napari:select_layer_above': [<KeyBinding at 0x7fa39b8a3c10: Ctrl+Up>], 'napari:select_layer_below': [<KeyBinding at 0x7fa39b8a3c70: Ctrl+Down>], 'napari:show_only_layer_above': [<KeyBinding at 0x7fa39b8a3cd0: Shift+Alt+Up>], 'napari:show_only_layer_below': [<KeyBinding at 0x7fa39b8a3d30: Shift+Alt+Down>], 'napari:hold_for_pan_zoom': [<KeyBinding at 0x7fa39b8a3d90: Space>], 'napari:activate_labels_erase_mode': [<KeyBinding at 0x7fa39b8a3e20: 1>, <KeyBinding at 0x7fa39b8a3eb0: E>], 'napari:activate_labels_paint_mode': [<KeyBinding at 0x7fa39b8a3f10: 2>, <KeyBinding at 0x7fa39b8a3fa0: P>], 'napari:activate_labels_polygon_mode': [<KeyBinding at 0x7fa39b8b0070: 3>], 'napari:activate_labels_fill_mode': [<KeyBinding at 0x7fa39b8b0100: 4>, <KeyBinding at 0x7fa39b8b0190: F>], 'napari:activate_labels_picker_mode': [<KeyBinding at 0x7fa39b8b0220: 5>, <KeyBinding at 0x7fa39b8b02b0: L>], 'napari:activate_labels_pan_zoom_mode': [<KeyBinding at 0x7fa39b8b0340: 6>, <KeyBinding at 0x7fa39b8b03d0: Z>], 'napari:activate_labels_transform_mode': [<KeyBinding at 0x7fa39b8b0460: 7>], 'napari:new_label': [<KeyBinding at 0x7fa39b8b04f0: M>], 'napari:swap_selected_and_background_labels': [<KeyBinding at 0x7fa39b8b0580: X>], 'napari:decrease_label_id': [<KeyBinding at 0x7fa39b8b0610: ->], 'napari:increase_label_id': [<KeyBinding at 0x7fa39b8b06a0: =>], 'napari:decrease_brush_size': [<KeyBinding at 0x7fa39b8b0730: [>], 'napari:increase_brush_size': [<KeyBinding at 0x7fa39b8b07c0: ]>], 'napari:toggle_preserve_labels': [<KeyBinding at 0x7fa39b8b0850: B>], 'napari:reset_polygon': [<KeyBinding at 0x7fa39b8b08e0: Escape>], 'napari:complete_polygon': [<KeyBinding at 0x7fa39b8b0970: Enter>], 'napari:activate_points_add_mode': [<KeyBinding at 0x7fa39b8b0a00: 2>, <KeyBinding at 0x7fa39b8b0a60: P>], 'napari:activate_points_select_mode': [<KeyBinding at 0x7fa39b8b0ac0: 3>, <KeyBinding at 0x7fa39b8b0b20: S>], 'napari:activate_points_pan_zoom_mode': [<KeyBinding at 0x7fa39b8b0bb0: 4>, <KeyBinding at 0x7fa39b8b0c10: Z>], 'napari:activate_points_transform_mode': [<KeyBinding at 0x7fa39b8b0c70: 5>], 'napari:select_all_in_slice': [<KeyBinding at 0x7fa39b8b0cd0: A>, <KeyBinding at 0x7fa39b8b0d60: Ctrl+A>], 'napari:select_all_data': [<KeyBinding at 0x7fa39b8b0dc0: Shift+A>], 'napari:delete_selected_points': [<KeyBinding at 0x7fa39b8b0e20: 1>, <KeyBinding at 0x7fa39b8b0e80: Delete>, <KeyBinding at 0x7fa39b8b0ee0: Backspace>], 'napari:activate_add_rectangle_mode': [<KeyBinding at 0x7fa39b8b0f40: R>], 'napari:activate_add_ellipse_mode': [<KeyBinding at 0x7fa39b8b0fa0: E>], 'napari:activate_add_line_mode': [<KeyBinding at 0x7fa39b8b1000: L>], 'napari:activate_add_path_mode': [<KeyBinding at 0x7fa39b8b1060: T>], 'napari:activate_add_polyline_mode': [<KeyBinding at 0x7fa39b8b10c0: Shift+L>], 'napari:activate_add_polygon_mode': [<KeyBinding at 0x7fa39b8b1120: P>], 'napari:activate_add_polygon_lasso_mode': [<KeyBinding at 0x7fa39b8b1180: Shift+P>], 'napari:activate_direct_mode': [<KeyBinding at 0x7fa39b8b11e0: 4>, <KeyBinding at 0x7fa39b8b1240: D>], 'napari:activate_select_mode': [<KeyBinding at 0x7fa39b8b12d0: 5>, <KeyBinding at 0x7fa39b8b1330: S>], 'napari:activate_shapes_pan_zoom_mode': [<KeyBinding at 0x7fa39b8b1390: 6>, <KeyBinding at 0x7fa39b8b13f0: Z>], 'napari:activate_shapes_transform_mode': [<KeyBinding at 0x7fa39b8b1450: 7>], 'napari:activate_vertex_insert_mode': [<KeyBinding at 0x7fa39b8b14b0: 2>, <KeyBinding at 0x7fa39b8b1510: I>], 'napari:activate_vertex_remove_mode': [<KeyBinding at 0x7fa39b8b15a0: 1>, <KeyBinding at 0x7fa39b8b1600: X>], 'napari:copy_selected_shapes': [<KeyBinding at 0x7fa39b8b1660: Ctrl+C>], 'napari:paste_shape': [<KeyBinding at 0x7fa39b8b16c0: Ctrl+V>], 'napari:move_shapes_selection_to_front': [<KeyBinding at 0x7fa39b8b1720: F>], 'napari:move_shapes_selection_to_back': [<KeyBinding at 0x7fa39b8b1780: B>], 'napari:select_all_shapes': [<KeyBinding at 0x7fa39b8b17e0: A>, <KeyBinding at 0x7fa39b8b1840: Ctrl+A>], 'napari:delete_selected_shapes': [<KeyBinding at 0x7fa39b8b18a0: 3>, <KeyBinding at 0x7fa39b8b1900: Delete>, <KeyBinding at 0x7fa39b8b1960: Backspace>], 'napari:finish_drawing_shape': [<KeyBinding at 0x7fa39b8b19c0: Enter>, <KeyBinding at 0x7fa39b8b1a20: Escape>], 'napari:orient_plane_normal_along_x': [<KeyBinding at 0x7fa39b8b1a80: X>], 'napari:orient_plane_normal_along_y': [<KeyBinding at 0x7fa39b8b1ae0: Y>], 'napari:orient_plane_normal_along_z': [<KeyBinding at 0x7fa39b8b1b40: Z>], 'napari:orient_plane_normal_along_view_direction': [<KeyBinding at 0x7fa39b8b1ba0: O>], 'napari:activate_image_pan_zoom_mode': [<KeyBinding at 0x7fa39b8b1c30: 1>], 'napari:activate_image_transform_mode': [<KeyBinding at 0x7fa39b8b1c90: 2>], 'napari:activate_vectors_pan_zoom_mode': [<KeyBinding at 0x7fa39b8b1cf0: 1>], 'napari:activate_vectors_transform_mode': [<KeyBinding at 0x7fa39b8b1d50: 2>], 'napari:activate_tracks_pan_zoom_mode': [<KeyBinding at 0x7fa39b8b1db0: 1>], 'napari:activate_tracks_transform_mode': [<KeyBinding at 0x7fa39b8b1e10: 2>], 'napari:activate_surface_pan_zoom_mode': [<KeyBinding at 0x7fa39b8b1e70: 1>], 'napari:activate_surface_transform_mode': [<KeyBinding at 0x7fa39b8b1ed0: 2>]}.

  • UI: This setting can be configured via the preferences dialog.

EXPERIMENTAL#

Experimental settings.

Render Images Asynchronously#

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

  • Access programmatically with SETTINGS.experimental.async_.

  • Type: bool.

  • Default: False.

  • UI: This setting can be configured via the preferences dialog.

Enable autoswapping rendering buffers.#

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

  • Access programmatically with SETTINGS.experimental.autoswap_buffers.

  • Type: bool.

  • Default: False.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: ColormapBackend.

  • Default: fastest_available.

  • UI: This setting can be configured via the preferences dialog.

Unused option. Use “triangulation backend” instead.#

This option was removed in napari 0.6.0. Use “triangulation backend” instead.

  • Access programmatically with SETTINGS.experimental.compiled_triangulation.

  • Type: bool.

  • Default: False.

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.

  • Type: int.

  • Default: -1.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: ConstrainedIntValue.

  • Default: 10.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: ConstrainedFloatValue.

  • Default: 0.5.

  • UI: This setting can be configured via the preferences dialog.

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.

  • Type: TriangulationBackend.

  • Default: fastest_available.

  • UI: This setting can be configured via the preferences dialog.

Support for plugin specific settings will be provided in an upcoming release.