1# Configuring Zed
  2
  3This guide explains how Zed's settings system works, including the Settings Editor, JSON configuration files, and project-specific settings.
  4
  5For visual customization (themes, fonts, icons), see [Appearance](./appearance.md).
  6
  7## Settings Editor
  8
  9The **Settings Editor** ({#kb zed::OpenSettings}) is the primary way to configure Zed. It provides a searchable interface where you can browse available settings, see their current values, and make changes.
 10
 11To open it:
 12
 13- Press {#kb zed::OpenSettings}
 14- Or run `zed: open settings` from the command palette
 15
 16As you type in the search box, matching settings appear with descriptions and controls to modify them. Changes save automatically to your settings file.
 17
 18> **Note:** Not all settings are available in the Settings Editor yet. Some advanced options, like language formatters, require editing the JSON file directly.
 19
 20## Settings Files
 21
 22### User Settings
 23
 24Your user settings apply globally across all projects. Open the file with {#kb zed::OpenSettingsFile} or run `zed: open settings file` from the command palette.
 25
 26The file is located at:
 27
 28- macOS: `~/.config/zed/settings.json`
 29- Linux: `~/.config/zed/settings.json` (or `$XDG_CONFIG_HOME/zed/settings.json`)
 30- Windows: `%APPDATA%\Zed\settings.json`
 31
 32The syntax is JSON with support for `//` comments.
 33
 34### Default Settings
 35
 36To see all available settings with their default values, run {#action zed::OpenDefaultSettings} from the command palette. This opens a read-only reference you can use when editing your own settings.
 37
 38### Project Settings
 39
 40Override user settings for a specific project by creating a `.zed/settings.json` file in your project root. Run {#action zed::OpenProjectSettings} to create this file.
 41
 42Project settings take precedence over user settings for that project only.
 43
 44```json [settings]
 45// .zed/settings.json
 46{
 47  "tab_size": 2,
 48  "formatter": "prettier",
 49  "format_on_save": "on"
 50}
 51```
 52
 53You can also add settings files in subdirectories for more granular control.
 54
 55**Limitation:** Not all settings can be set at the project level. Settings that affect the editor globally (like `theme` or `vim_mode`) only work in user settings. Project settings are limited to editor behavior and language tooling options like `tab_size`, `formatter`, and `format_on_save`.
 56
 57## How Settings Merge
 58
 59Settings are applied in layers:
 60
 611. **Default settings** — Zed's built-in defaults
 622. **User settings** — Your global preferences
 633. **Project settings** — Project-specific overrides
 64
 65Later layers override earlier ones. For object settings (like `terminal`), properties merge rather than replace entirely.
 66
 67## Per-Release Channel Overrides
 68
 69Use different settings for Stable, Preview, or Nightly builds by adding top-level channel keys:
 70
 71```json [settings]
 72{
 73  "theme": "One Dark",
 74  "vim_mode": false,
 75  "nightly": {
 76    "theme": "Rosé Pine",
 77    "vim_mode": true
 78  },
 79  "preview": {
 80    "theme": "Catppuccin Mocha"
 81  }
 82}
 83```
 84
 85With this configuration:
 86
 87- **Stable** uses One Dark with vim mode off
 88- **Preview** uses Catppuccin Mocha with vim mode off
 89- **Nightly** uses Rosé Pine with vim mode on
 90
 91Changes made in the Settings Editor apply across all channels.
 92
 93## Settings Deep Links
 94
 95Zed supports deep links that open specific settings directly:
 96
 97```
 98zed://settings/theme
 99zed://settings/vim_mode
100zed://settings/buffer_font_size
101```
102
103These are useful for sharing configuration tips or linking from documentation.
104
105## Example Configuration
106
107```json [settings]
108{
109  "theme": {
110    "mode": "system",
111    "light": "One Light",
112    "dark": "One Dark"
113  },
114  "buffer_font_family": "JetBrains Mono",
115  "buffer_font_size": 14,
116  "tab_size": 2,
117  "format_on_save": "on",
118  "autosave": "on_focus_change",
119  "vim_mode": false,
120  "terminal": {
121    "font_family": "JetBrains Mono",
122    "font_size": 14
123  },
124  "languages": {
125    "Python": {
126      "tab_size": 4
127    }
128  }
129}
130```
131
132## What's Next
133
134- [Appearance](./appearance.md) — Themes, fonts, and visual customization
135- [Key bindings](./key-bindings.md) — Customize keyboard shortcuts
136- [All Settings](./reference/all-settings.md) — Complete settings reference