Skip to main content
nteract Desktop settings control default behavior for new notebooks, appearance, and runtime configuration.

​
Quick Reference

SettingOptionsDefaultStored In
Themelight, dark, systemsystemSynced (Automerge) + settings file
Default runtimepython, denopythonSynced (Automerge) + settings file
Default Python envuv, condauvSynced (Automerge) + settings file
Default uv packageslist of strings(empty)Synced (Automerge) + settings file
Default conda packageslist of strings(empty)Synced (Automerge) + settings file

​
How Settings Sync Works

Settings are synced across all notebook windows via the runtimed daemon using Automerge. The daemon holds the canonical document; each notebook window maintains a local replica.
When you change a setting in any window, it propagates to all other open windows in real time.

​
Sync Architecture

  • Source of truth: The Automerge document in the daemon
  • Persistence: Settings are also written to settings.json in the same nested format
  • External edits: The daemon watches settings.json for external changes (manual edits, CLI tools) and propagates them to all connected windows automatically
  • Fallback: When the daemon is unavailable, settings are read directly from settings.json
  • Theme special case: Theme also uses browser localStorage to prevent a flash of unstyled content on startup

​
Automerge Document Structure

The synced settings use nested maps for environment-specific configuration: 
ROOT/
  theme: "system"
  default_runtime: "python"
  default_python_env: "uv"
  uv/                                         ← nested Map
    default_packages: List["numpy", "pandas"] ← List of Str
  conda/                                      ← nested Map
    default_packages: List["scipy"]           ← List of Str
Environment-specific settings (packages, future: channels) live under uv/ and conda/ sub-maps, making the schema extensible without adding more root-level keys.

​
Settings File

Settings are persisted to a JSON file shared across all notebook windows. Both the daemon and the notebook app write the same nested JSON format. 
~/Library/Application Support/nteract/settings.json
The file is created automatically when you first change a setting. You can also edit it by hand — changes are detected and applied automatically when the daemon is running.

​
Example Settings File

{
  "theme": "system",
  "default_runtime": "python",
  "default_python_env": "uv",
  "uv": {
    "default_packages": ["numpy", "pandas", "matplotlib"]
  },
  "conda": {
    "default_packages": ["numpy", "pandas", "scikit-learn"]
  }
}

​
JSON Schema

The settings structs derive schemars::JsonSchema. Both SyncedSettings (in runtimed) and AppSettings (in the notebook crate) serialize to the same JSON schema.

​
Theme

Controls light/dark appearance for the notebook editor and output viewer.
  • Light — forces light mode
  • Dark — forces dark mode
  • System — follows your OS preference and updates automatically when it changes
1

Open Settings

Click the gear icon in the notebook toolbar
2

Select Theme

Choose Light, Dark, or System from the theme options

​
Default Runtime

Determines which runtime is used when creating a new notebook with Cmd+N (or Ctrl+N on Windows/Linux). 
{
  "default_runtime": "python"
}
Valid values: "python", "deno"
You can always create a notebook with a specific runtime using the File > New Notebook As… submenu.

​
Opening Notebooks

  • Open existing notebook: Use File > Open > Open… to select from the file picker
  • Sample notebooks: Browse bundled examples under File > Open > Sample Notebooks

​
Default Python Environment

Controls which package manager is used for Python notebooks when no project-level configuration is detected. 
{
  "default_python_env": "uv"
}
Valid values: "uv", "conda"
  • uv — uses uv for package management (fast, pip-compatible)
  • conda — uses conda/rattler for package management (supports conda packages)
If the notebook directory contains a pyproject.toml or environment.yml, the environment type is determined by that file instead of this setting.

​
Default Packages

Controls which packages are pre-installed in prewarmed environments. These packages are available immediately when you open a new notebook, without needing to add them as inline dependencies. Since uv and conda have different package ecosystems, packages are configured separately: 
{
  "uv": {
    "default_packages": ["numpy", "pandas", "matplotlib"]
  },
  "conda": {
    "default_packages": ["numpy", "pandas", "scikit-learn"]
  }
}
Changes take effect on the next pool replenishment cycle — existing prewarmed environments keep their original packages until replaced. Restarting the app clears the pool and rebuilds with the updated packages.
The packages are installed alongside ipykernel and ipywidgets (which are always included).

Build docs developers (and LLMs) love

Get started for freeTalk to us