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.191691776).

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

Proportional spacing between grid layers.

  • Access programmatically with SETTINGS.application.grid_spacing.

  • Type: ConstrainedFloatValue.

  • Default: 0.0.

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

Grid Stride#

Number of layers to place in each grid square.

  • 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 0x7f39283f3eb0: Ctrl+Shift+C>], 'napari:reset_scroll_progress': [<KeyBinding at 0x7f39283f3dc0: Ctrl>], 'napari:toggle_ndisplay': [<KeyBinding at 0x7f39283f3970: Ctrl+Y>], 'napari:toggle_theme': [<KeyBinding at 0x7f39283f36d0: Ctrl+Shift+T>], 'napari:reset_view': [<KeyBinding at 0x7f39283f3df0: Ctrl+R>], 'napari:delete_selected_layers': [<KeyBinding at 0x7f39283f3f40: Ctrl+Delete>, <KeyBinding at 0x7f39283f3fd0: Ctrl+Backspace>], 'napari:show_shortcuts': [<KeyBinding at 0x7f39277000a0: Ctrl+Alt+/>], 'napari:increment_dims_left': [<KeyBinding at 0x7f3927700130: Left>], 'napari:increment_dims_right': [<KeyBinding at 0x7f39277001c0: Right>], 'napari:focus_axes_up': [<KeyBinding at 0x7f3927700250: Alt+Up>], 'napari:focus_axes_down': [<KeyBinding at 0x7f39277002e0: Alt+Down>], 'napari:roll_axes': [<KeyBinding at 0x7f3927700370: Ctrl+E>], 'napari:transpose_axes': [<KeyBinding at 0x7f3927700400: Ctrl+T>], 'napari:rotate_layers': [<KeyBinding at 0x7f3927700460: Ctrl+Alt+T>], 'napari:toggle_grid': [<KeyBinding at 0x7f39277004c0: Ctrl+G>], 'napari:toggle_selected_visibility': [<KeyBinding at 0x7f3927700550: V>], 'napari:toggle_unselected_visibility': [<KeyBinding at 0x7f39277005e0: Shift+V>], 'napari:show_only_layer_above': [<KeyBinding at 0x7f3927700640: Shift+Alt+Up>], 'napari:show_only_layer_below': [<KeyBinding at 0x7f39277006a0: Shift+Alt+Down>], 'napari:hold_for_pan_zoom': [<KeyBinding at 0x7f3927700700: Space>], 'napari:activate_labels_erase_mode': [<KeyBinding at 0x7f3927700790: 1>, <KeyBinding at 0x7f3927700820: E>], 'napari:activate_labels_paint_mode': [<KeyBinding at 0x7f3927700880: 2>, <KeyBinding at 0x7f3927700910: P>], 'napari:activate_labels_polygon_mode': [<KeyBinding at 0x7f39277009a0: 3>], 'napari:activate_labels_fill_mode': [<KeyBinding at 0x7f3927700a30: 4>, <KeyBinding at 0x7f3927700ac0: F>], 'napari:activate_labels_picker_mode': [<KeyBinding at 0x7f39283d7880: 5>, <KeyBinding at 0x7f39283d7a00: L>], 'napari:activate_labels_pan_zoom_mode': [<KeyBinding at 0x7f39283d7af0: 6>, <KeyBinding at 0x7f39283d7e50: Z>], 'napari:activate_labels_transform_mode': [<KeyBinding at 0x7f39283d7cd0: 7>], 'napari:new_label': [<KeyBinding at 0x7f39283d7d30: M>], 'napari:swap_selected_and_background_labels': [<KeyBinding at 0x7f39283d7ee0: X>], 'napari:decrease_label_id': [<KeyBinding at 0x7f39283d7fd0: ->], 'napari:increase_label_id': [<KeyBinding at 0x7f3927700b50: =>], 'napari:decrease_brush_size': [<KeyBinding at 0x7f3927700be0: [>], 'napari:increase_brush_size': [<KeyBinding at 0x7f3927700c70: ]>], 'napari:toggle_preserve_labels': [<KeyBinding at 0x7f3927700d00: B>], 'napari:reset_polygon': [<KeyBinding at 0x7f3927700d90: Escape>], 'napari:complete_polygon': [<KeyBinding at 0x7f3927700e20: Enter>], 'napari:activate_points_add_mode': [<KeyBinding at 0x7f3927700eb0: 2>, <KeyBinding at 0x7f3927700f10: P>], 'napari:activate_points_select_mode': [<KeyBinding at 0x7f3927700f70: 3>, <KeyBinding at 0x7f3927700fd0: S>], 'napari:activate_points_pan_zoom_mode': [<KeyBinding at 0x7f3927701060: 4>, <KeyBinding at 0x7f39277010c0: Z>], 'napari:activate_points_transform_mode': [<KeyBinding at 0x7f3927701120: 5>], 'napari:select_all_in_slice': [<KeyBinding at 0x7f3927701180: A>, <KeyBinding at 0x7f3927701210: Ctrl+A>], 'napari:select_all_data': [<KeyBinding at 0x7f3927701270: Shift+A>], 'napari:delete_selected_points': [<KeyBinding at 0x7f39277012d0: 1>, <KeyBinding at 0x7f3927701330: Delete>, <KeyBinding at 0x7f3927701390: Backspace>], 'napari:activate_add_rectangle_mode': [<KeyBinding at 0x7f39277013f0: R>], 'napari:activate_add_ellipse_mode': [<KeyBinding at 0x7f3927701450: E>], 'napari:activate_add_line_mode': [<KeyBinding at 0x7f39277014b0: L>], 'napari:activate_add_path_mode': [<KeyBinding at 0x7f3927701510: T>], 'napari:activate_add_polyline_mode': [<KeyBinding at 0x7f3927701570: Shift+L>], 'napari:activate_add_polygon_mode': [<KeyBinding at 0x7f39277015d0: P>], 'napari:activate_add_polygon_lasso_mode': [<KeyBinding at 0x7f3927701630: Shift+P>], 'napari:activate_direct_mode': [<KeyBinding at 0x7f3927701690: 4>, <KeyBinding at 0x7f39277016f0: D>], 'napari:activate_select_mode': [<KeyBinding at 0x7f3927701780: 5>, <KeyBinding at 0x7f39277017e0: S>], 'napari:activate_shapes_pan_zoom_mode': [<KeyBinding at 0x7f3927701840: 6>, <KeyBinding at 0x7f39277018a0: Z>], 'napari:activate_shapes_transform_mode': [<KeyBinding at 0x7f3927701900: 7>], 'napari:activate_vertex_insert_mode': [<KeyBinding at 0x7f3927701960: 2>, <KeyBinding at 0x7f39277019c0: I>], 'napari:activate_vertex_remove_mode': [<KeyBinding at 0x7f3927701a50: 1>, <KeyBinding at 0x7f3927701ab0: X>], 'napari:copy_selected_shapes': [<KeyBinding at 0x7f3927701b10: Ctrl+C>], 'napari:paste_shape': [<KeyBinding at 0x7f3927701b70: Ctrl+V>], 'napari:move_shapes_selection_to_front': [<KeyBinding at 0x7f3927701bd0: F>], 'napari:move_shapes_selection_to_back': [<KeyBinding at 0x7f3927701c30: B>], 'napari:select_all_shapes': [<KeyBinding at 0x7f3927701c90: A>], 'napari:delete_selected_shapes': [<KeyBinding at 0x7f3927701cf0: 3>, <KeyBinding at 0x7f3927701d50: Delete>, <KeyBinding at 0x7f3927701db0: Backspace>], 'napari:finish_drawing_shape': [<KeyBinding at 0x7f3927701e10: Enter>, <KeyBinding at 0x7f3927701e70: Escape>], 'napari:orient_plane_normal_along_x': [<KeyBinding at 0x7f3927701ed0: X>], 'napari:orient_plane_normal_along_y': [<KeyBinding at 0x7f3927701f30: Y>], 'napari:orient_plane_normal_along_z': [<KeyBinding at 0x7f3927701f90: Z>], 'napari:orient_plane_normal_along_view_direction': [<KeyBinding at 0x7f3927701ff0: O>], 'napari:activate_image_pan_zoom_mode': [<KeyBinding at 0x7f3927702080: 1>], 'napari:activate_image_transform_mode': [<KeyBinding at 0x7f39277020e0: 2>], 'napari:activate_vectors_pan_zoom_mode': [<KeyBinding at 0x7f3927702140: 1>], 'napari:activate_vectors_transform_mode': [<KeyBinding at 0x7f39277021a0: 2>], 'napari:activate_tracks_pan_zoom_mode': [<KeyBinding at 0x7f3927702200: 1>], 'napari:activate_tracks_transform_mode': [<KeyBinding at 0x7f3927702260: 2>], 'napari:activate_surface_pan_zoom_mode': [<KeyBinding at 0x7f39277022c0: 1>], 'napari:activate_surface_transform_mode': [<KeyBinding at 0x7f3927702320: 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.

Use C++ code to speed up creation and updates of Shapes layers(requires optional dependencies)#

When enabled, triangulation (breaking down polygons into triangles that can be displayed by napari’s graphics engine) is sped up by using C++ code from the optional library PartSegCore-compiled-backend. C++ code can cause bad crashes called segmentation faults or access violations. If you encounter such a crash while using this option please report it at napari/napari#issues.

  • Access programmatically with SETTINGS.experimental.compiled_triangulation.

  • Type: bool.

  • Default: False.

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

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.

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