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-file Settings
73
74Zed has some compatibility support for Emacs and Vim [modelines](./modelines.md), so you can set some settings per-file.
75
76## Per-Release Channel Overrides
77
78Use different settings for Stable, Preview, or Nightly builds by adding top-level channel keys:
79
80```json [settings]
81{
82 "theme": "One Dark",
83 "vim_mode": false,
84 "nightly": {
85 "theme": "Rosé Pine",
86 "vim_mode": true
87 },
88 "preview": {
89 "theme": "Catppuccin Mocha"
90 }
91}
92```
93
94With this configuration:
95
96- **Stable** uses One Dark with vim mode off
97- **Preview** uses Catppuccin Mocha with vim mode off
98- **Nightly** uses Rosé Pine with vim mode on
99
100Changes made in the Settings Editor apply across all channels.
101
102## Settings Deep Links
103
104Zed supports deep links that open specific settings directly:
105
106```
107zed://settings/theme
108zed://settings/vim_mode
109zed://settings/buffer_font_size
110```
111
112These are useful for sharing configuration tips or linking from documentation.
113
114## Example Configuration
115
116```json [settings]
117{
118 "theme": {
119 "mode": "system",
120 "light": "One Light",
121 "dark": "One Dark"
122 },
123 "buffer_font_family": "JetBrains Mono",
124 "buffer_font_size": 14,
125 "tab_size": 2,
126 "format_on_save": "on",
127 "autosave": "on_focus_change",
128 "vim_mode": false,
129 "terminal": {
130 "font_family": "JetBrains Mono",
131 "font_size": 14
132 },
133 "languages": {
134 "Python": {
135 "tab_size": 4
136 }
137 }
138}
139```
140
141## What's Next
142
143- [Appearance](./appearance.md) — Themes, fonts, and visual customization
144- [Key bindings](./key-bindings.md) — Customize keyboard shortcuts
145- [AI Configuration](./ai/configuration.md) — Set up AI providers, models, and agent settings
146- [All Settings](./reference/all-settings.md) — Complete settings reference