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