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