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