1# Configuring Zed
2
3Zed is designed to be configured: we want to fit your workflow and preferences exactly. We provide default settings that are designed to be a comfortable starting point for as many people as possible, but we hope you will enjoy tweaking it to make it feel incredible.
4
5In addition to the settings described here, you may also want to change your [theme](./themes.md), configure your [key bindings](./key-bindings.md), set up [tasks](./tasks.md) or install [extensions](https://github.com/zed-industries/extensions).
6
7## Settings files
8
9<!--
10TBD: Settings files. Rewrite with "remote settings" in mind (e.g. `local settings` on the remote host).
11Consider renaming `zed: Open Local Settings` to `zed: Open Project Settings`.
12
13TBD: Add settings documentation about how settings are merged as overlays. E.g. project>local>default. Note how settings that are maps are merged, but settings that are arrays are replaced and must include the defaults.
14-->
15
16Your settings file can be opened with {#kb zed::OpenSettings}. By default it is located at `~/.config/zed/settings.json`, though if you have XDG_CONFIG_HOME in your environment on Linux it will be at `$XDG_CONFIG_HOME/zed/settings.json` instead.
17
18This configuration is merged with any local configuration inside your projects. You can open the project settings by running {#action zed::OpenProjectSettings} from the command palette. This will create a `.zed` directory containing`.zed/settings.json`.
19
20Although most projects will only need one settings file at the root, you can add more local settings files for subdirectories as needed. Not all settings can be set in local files, just those that impact the behavior of the editor and language tooling. For example you can set `tab_size`, `formatter` etc. but not `theme`, `vim_mode` and similar.
21
22The syntax for configuration files is a super-set of JSON that allows `//` comments.
23
24## Default settings
25
26You can find the default settings for your current Zed by running {#action zed::OpenDefaultSettings} from the command palette.
27
28Extensions that provide language servers may also provide default settings for those language servers.
29
30# Settings
31
32## Active Pane Modifiers
33
34- Description: Styling settings applied to the active pane.
35- Setting: `active_pane_modifiers`
36- Default:
37
38```json
39{
40 "active_pane_modifiers": {
41 "magnification": 1.0,
42 "border_size": 0.0,
43 "inactive_opacity": 1.0
44 }
45}
46```
47
48### Magnification
49
50- Description: Scale by which to zoom the active pane. When set to `1.0`, the active pane has the same size as others, but when set to a larger value, the active pane takes up more space.
51- Setting: `magnification`
52- Default: `1.0`
53
54**Options**
55
56`float` values
57
58### Border size
59
60- Description: Size of the border surrounding the active pane. When set to 0, the active pane doesn't have any border. The border is drawn inset.
61- Setting: `border_size`
62- Default: `0.0`
63
64**Options**
65
66Non-negative `float` values
67
68### Inactive Opacity
69
70- Description: Opacity of inactive panels. When set to 1.0, the inactive panes have the same opacity as the active one. If set to 0, the inactive panes content will not be visible at all. Values are clamped to the [0.0, 1.0] range.
71- Setting: `inactive_opacity`
72- Default: `1.0`
73
74**Options**
75
76`float` values
77
78## Bottom Dock Layout
79
80- Description: Control the layout of the bottom dock, relative to the left and right docks
81- Setting: `bottom_dock_layout`
82- Default: `"contained"`
83
84**Options**
85
861. Contain the bottom dock, giving the full height of the window to the left and right docks
87
88```json
89{
90 "bottom_dock_layout": "contained"
91}
92```
93
942. Give the bottom dock the full width of the window, truncating the left and right docks
95
96```json
97{
98 "bottom_dock_layout": "full"
99}
100```
101
1023. Left align the bottom dock, truncating the left dock and giving the right dock the full height of the window
103
104```json
105{
106 "bottom_dock_layout": "left_aligned"
107}
108```
109
1103. Right align the bottom dock, giving the left dock the full height of the window and truncating the right dock.
111
112```json
113{
114 "bottom_dock_layout": "right_aligned"
115}
116```
117
118## Auto Install extensions
119
120- Description: Define extensions to be autoinstalled or never be installed.
121- Setting: `auto_install_extension`
122- Default: `{ "html": true }`
123
124**Options**
125
126You can find the names of your currently installed extensions by listing the subfolders under the [extension installation location](./extensions/installing-extensions#installation-location):
127
128On MacOS:
129
130```sh
131ls ~/Library/Application\ Support/Zed/extensions/installed/
132```
133
134On Linux:
135
136```sh
137ls ~/.local/share/zed/extensions/installed
138```
139
140Define extensions which should be installed (`true`) or never installed (`false`).
141
142```json
143{
144 "auto_install_extensions": {
145 "html": true,
146 "dockerfile": true,
147 "docker-compose": false
148 }
149}
150```
151
152## Autosave
153
154- Description: When to automatically save edited buffers.
155- Setting: `autosave`
156- Default: `off`
157
158**Options**
159
1601. To disable autosave, set it to `off`:
161
162```json
163{
164 "autosave": "off"
165}
166```
167
1682. To autosave when focus changes, use `on_focus_change`:
169
170```json
171{
172 "autosave": "on_focus_change"
173}
174```
175
1763. To autosave when the active window changes, use `on_window_change`:
177
178```json
179{
180 "autosave": "on_window_change"
181}
182```
183
1844. To autosave after an inactivity period, use `after_delay`:
185
186```json
187{
188 "autosave": {
189 "after_delay": {
190 "milliseconds": 1000
191 }
192 }
193}
194```
195
196## Restore on Startup
197
198- Description: Controls session restoration on startup.
199- Setting: `restore_on_startup`
200- Default: `last_session`
201
202**Options**
203
2041. Restore all workspaces that were open when quitting Zed:
205
206```json
207{
208 "restore_on_startup": "last_session"
209}
210```
211
2122. Restore the workspace that was closed last:
213
214```json
215{
216 "restore_on_startup": "last_workspace"
217}
218```
219
2203. Always start with an empty editor:
221
222```json
223{
224 "restore_on_startup": "none"
225}
226```
227
228## Autoscroll on Clicks
229
230- Description: Whether to scroll when clicking near the edge of the visible text area.
231- Setting: `autoscroll_on_clicks`
232- Default: `false`
233
234**Options**
235
236`boolean` values
237
238## Auto Update
239
240- Description: Whether or not to automatically check for updates.
241- Setting: `auto_update`
242- Default: `true`
243
244**Options**
245
246`boolean` values
247
248## Base Keymap
249
250- Description: Base key bindings scheme. Base keymaps can be overridden with user keymaps.
251- Setting: `base_keymap`
252- Default: `VSCode`
253
254**Options**
255
2561. VSCode
257
258```json
259{
260 "base_keymap": "VSCode"
261}
262```
263
2642. Atom
265
266```json
267{
268 "base_keymap": "Atom"
269}
270```
271
2723. JetBrains
273
274```json
275{
276 "base_keymap": "JetBrains"
277}
278```
279
2804. None
281
282```json
283{
284 "base_keymap": "None"
285}
286```
287
2885. SublimeText
289
290```json
291{
292 "base_keymap": "SublimeText"
293}
294```
295
2966. TextMate
297
298```json
299{
300 "base_keymap": "TextMate"
301}
302```
303
304## Buffer Font Family
305
306- Description: The name of a font to use for rendering text in the editor.
307- Setting: `buffer_font_family`
308- Default: `Zed Plex Mono`
309
310**Options**
311
312The name of any font family installed on the user's system
313
314## Buffer Font Features
315
316- Description: The OpenType features to enable for text in the editor.
317- Setting: `buffer_font_features`
318- Default: `null`
319- Platform: macOS and Windows.
320
321**Options**
322
323Zed supports all OpenType features that can be enabled or disabled for a given buffer or terminal font, as well as setting values for font features.
324
325For example, to disable font ligatures, add the following to your settings:
326
327```json
328{
329 "buffer_font_features": {
330 "calt": false
331 }
332}
333```
334
335You can also set other OpenType features, like setting `cv01` to `7`:
336
337```json
338{
339 "buffer_font_features": {
340 "cv01": 7
341 }
342}
343```
344
345## Buffer Font Fallbacks
346
347- Description: Set the buffer text's font fallbacks, this will be merged with the platform's default fallbacks.
348- Setting: `buffer_font_fallbacks`
349- Default: `null`
350- Platform: macOS and Windows.
351
352**Options**
353
354For example, to use `Nerd Font` as a fallback, add the following to your settings:
355
356```json
357{
358 "buffer_font_fallbacks": ["Nerd Font"]
359}
360```
361
362## Buffer Font Size
363
364- Description: The default font size for text in the editor.
365- Setting: `buffer_font_size`
366- Default: `15`
367
368**Options**
369
370`integer` values from `6` to `100` pixels (inclusive)
371
372## Buffer Font Weight
373
374- Description: The default font weight for text in the editor.
375- Setting: `buffer_font_weight`
376- Default: `400`
377
378**Options**
379
380`integer` values between `100` and `900`
381
382## Buffer Line Height
383
384- Description: The default line height for text in the editor.
385- Setting: `buffer_line_height`
386- Default: `"comfortable"`
387
388**Options**
389
390`"standard"`, `"comfortable"` or `{ "custom": float }` (`1` is compact, `2` is loose)
391
392## Confirm Quit
393
394- Description: Whether or not to prompt the user to confirm before closing the application.
395- Setting: `confirm_quit`
396- Default: `false`
397
398**Options**
399
400`boolean` values
401
402## Centered Layout
403
404- Description: Configuration for the centered layout mode.
405- Setting: `centered_layout`
406- Default:
407
408```json
409"centered_layout": {
410 "left_padding": 0.2,
411 "right_padding": 0.2,
412}
413```
414
415**Options**
416
417The `left_padding` and `right_padding` options define the relative width of the
418left and right padding of the central pane from the workspace when the centered layout mode is activated. Valid values range is from `0` to `0.4`.
419
420## Direnv Integration
421
422- Description: Settings for [direnv](https://direnv.net/) integration. Requires `direnv` to be installed.
423 `direnv` integration make it possible to use the environment variables set by a `direnv` configuration to detect some language servers in `$PATH` instead of installing them.
424 It also allows for those environment variables to be used in tasks.
425- Setting: `load_direnv`
426- Default: `"direct"`
427
428**Options**
429
430There are two options to choose from:
431
4321. `shell_hook`: Use the shell hook to load direnv. This relies on direnv to activate upon entering the directory. Supports POSIX shells and fish.
4332. `direct`: Use `direnv export json` to load direnv. This will load direnv directly without relying on the shell hook and might cause some inconsistencies. This allows direnv to work with any shell.
434
435## Edit Predictions
436
437- Description: Settings for edit predictions.
438- Setting: `edit_predictions`
439- Default:
440
441```json
442 "edit_predictions": {
443 "disabled_globs": [
444 "**/.env*",
445 "**/*.pem",
446 "**/*.key",
447 "**/*.cert",
448 "**/*.crt",
449 "**/.dev.vars",
450 "**/secrets.yml"
451 ]
452 }
453```
454
455**Options**
456
457### Disabled Globs
458
459- Description: A list of globs for which edit predictions should be disabled for. This list adds to a pre-existing, sensible default set of globs. Any additional ones you add are combined with them.
460- Setting: `disabled_globs`
461- Default: `["**/.env*", "**/*.pem", "**/*.key", "**/*.cert", "**/*.crt", "**/.dev.vars", "**/secrets.yml"]`
462
463**Options**
464
465List of `string` values.
466
467## Edit Predictions Disabled in
468
469- Description: A list of language scopes in which edit predictions should be disabled.
470- Setting: `edit_predictions_disabled_in`
471- Default: `[]`
472
473**Options**
474
475List of `string` values
476
4771. Don't show edit predictions in comments:
478
479```json
480"disabled_in": ["comment"]
481```
482
4832. Don't show edit predictions in strings and comments:
484
485```json
486"disabled_in": ["comment", "string"]
487```
488
4893. Only in Go, don't show edit predictions in strings and comments:
490
491```json
492{
493 "languages": {
494 "Go": {
495 "edit_predictions_disabled_in": ["comment", "string"]
496 }
497 }
498}
499```
500
501## Current Line Highlight
502
503- Description: How to highlight the current line in the editor.
504- Setting: `current_line_highlight`
505- Default: `all`
506
507**Options**
508
5091. Don't highlight the current line:
510
511```json
512"current_line_highlight": "none"
513```
514
5152. Highlight the gutter area:
516
517```json
518"current_line_highlight": "gutter"
519```
520
5213. Highlight the editor area:
522
523```json
524"current_line_highlight": "line"
525```
526
5274. Highlight the full line:
528
529```json
530"current_line_highlight": "all"
531```
532
533## Selection Highlight
534
535- Description: Whether to highlight all occurrences of the selected text in an editor.
536- Setting: `selection_highlight`
537- Default: `true`
538
539## Selection Highlight Debounce
540
541- Description: The debounce delay before querying highlights based on the selected text.
542
543- Setting: `selection_highlight_debounce`
544- Default: `50`
545
546## LSP Highlight Debounce
547
548- Description: The debounce delay before querying highlights from the language server based on the current cursor location.
549- Setting: `lsp_highlight_debounce`
550- Default: `75`
551
552## Cursor Blink
553
554- Description: Whether or not the cursor blinks.
555- Setting: `cursor_blink`
556- Default: `true`
557
558**Options**
559
560`boolean` values
561
562## Cursor Shape
563
564- Description: Cursor shape for the default editor.
565- Setting: `cursor_shape`
566- Default: `bar`
567
568**Options**
569
5701. A vertical bar:
571
572```json
573"cursor_shape": "bar"
574```
575
5762. A block that surrounds the following character:
577
578```json
579"cursor_shape": "block"
580```
581
5823. An underline / underscore that runs along the following character:
583
584```json
585"cursor_shape": "underline"
586```
587
5884. An box drawn around the following character:
589
590```json
591"cursor_shape": "hollow"
592```
593
594## Hide Mouse
595
596- Description: Determines when the mouse cursor should be hidden in an editor or input box.
597- Setting: `hide_mouse`
598- Default: `on_typing_and_movement`
599
600**Options**
601
602`boolean` values
603
604## Editor Scrollbar
605
606- Description: Whether or not to show the editor scrollbar and various elements in it.
607- Setting: `scrollbar`
608- Default:
609
610```json
611"scrollbar": {
612 "show": "auto",
613 "cursors": true,
614 "git_diff": true,
615 "search_results": true,
616 "selected_text": true,
617 "selected_symbol": true,
618 "diagnostics": "all",
619 "axes": {
620 "horizontal": true,
621 "vertical": true,
622 },
623},
624```
625
626### Show Mode
627
628- Description: When to show the editor scrollbar.
629- Setting: `show`
630- Default: `auto`
631
632**Options**
633
6341. Show the scrollbar if there's important information or follow the system's configured behavior:
635
636```json
637"scrollbar": {
638 "show": "auto"
639}
640```
641
6422. Match the system's configured behavior:
643
644```json
645"scrollbar": {
646 "show": "system"
647}
648```
649
6503. Always show the scrollbar:
651
652```json
653"scrollbar": {
654 "show": "always"
655}
656```
657
6584. Never show the scrollbar:
659
660```json
661"scrollbar": {
662 "show": "never"
663}
664```
665
666### Cursor Indicators
667
668- Description: Whether to show cursor positions in the scrollbar.
669- Setting: `cursors`
670- Default: `true`
671
672**Options**
673
674`boolean` values
675
676### Git Diff Indicators
677
678- Description: Whether to show git diff indicators in the scrollbar.
679- Setting: `git_diff`
680- Default: `true`
681
682**Options**
683
684`boolean` values
685
686### Search Results Indicators
687
688- Description: Whether to show buffer search results in the scrollbar.
689- Setting: `search_results`
690- Default: `true`
691
692**Options**
693
694`boolean` values
695
696### Selected Text Indicators
697
698- Description: Whether to show selected text occurrences in the scrollbar.
699- Setting: `selected_text`
700- Default: `true`
701
702**Options**
703
704`boolean` values
705
706### Selected Symbols Indicators
707
708- Description: Whether to show selected symbol occurrences in the scrollbar.
709- Setting: `selected_symbol`
710- Default: `true`
711
712**Options**
713
714`boolean` values
715
716### Diagnostics
717
718- Description: Which diagnostic indicators to show in the scrollbar.
719- Setting: `diagnostics`
720- Default: `all`
721
722**Options**
723
7241. Show all diagnostics:
725
726```json
727{
728 "diagnostics": "all"
729}
730```
731
7322. Do not show any diagnostics:
733
734```json
735{
736 "diagnostics": "none"
737}
738```
739
7403. Show only errors:
741
742```json
743{
744 "diagnostics": "error"
745}
746```
747
7484. Show only errors and warnings:
749
750```json
751{
752 "diagnostics": "warning"
753}
754```
755
7565. Show only errors, warnings, and information:
757
758```json
759{
760 "diagnostics": "information"
761}
762```
763
764### Axes
765
766- Description: Forcefully enable or disable the scrollbar for each axis
767- Setting: `axes`
768- Default:
769
770```json
771"scrollbar": {
772 "axes": {
773 "horizontal": true,
774 "vertical": true,
775 },
776}
777```
778
779#### Horizontal
780
781- Description: When false, forcefully disables the horizontal scrollbar. Otherwise, obey other settings.
782- Setting: `horizontal`
783- Default: `true`
784
785**Options**
786
787`boolean` values
788
789#### Vertical
790
791- Description: When false, forcefully disables the vertical scrollbar. Otherwise, obey other settings.
792- Setting: `vertical`
793- Default: `true`
794
795**Options**
796
797`boolean` values
798
799## Editor Tab Bar
800
801- Description: Settings related to the editor's tab bar.
802- Settings: `tab_bar`
803- Default:
804
805```json
806"tab_bar": {
807 "show": true,
808 "show_nav_history_buttons": true,
809 "show_tab_bar_buttons": true
810}
811```
812
813### Show
814
815- Description: Whether or not to show the tab bar in the editor.
816- Setting: `show`
817- Default: `true`
818
819**Options**
820
821`boolean` values
822
823### Navigation History Buttons
824
825- Description: Whether or not to show the navigation history buttons.
826- Setting: `show_nav_history_buttons`
827- Default: `true`
828
829**Options**
830
831`boolean` values
832
833### Tab Bar Buttons
834
835- Description: Whether or not to show the tab bar buttons.
836- Setting: `show_tab_bar_buttons`
837- Default: `true`
838
839**Options**
840
841`boolean` values
842
843## Editor Tabs
844
845- Description: Configuration for the editor tabs.
846- Setting: `tabs`
847- Default:
848
849```json
850"tabs": {
851 "close_position": "right",
852 "file_icons": false,
853 "git_status": false,
854 "activate_on_close": "history",
855 "show_close_button": "hover",
856 "show_diagnostics": "off"
857},
858```
859
860### Close Position
861
862- Description: Where to display close button within a tab.
863- Setting: `close_position`
864- Default: `right`
865
866**Options**
867
8681. Display the close button on the right:
869
870```json
871{
872 "close_position": "right"
873}
874```
875
8762. Display the close button on the left:
877
878```json
879{
880 "close_position": "left"
881}
882```
883
884### File Icons
885
886- Description: Whether to show the file icon for a tab.
887- Setting: `file_icons`
888- Default: `false`
889
890### Git Status
891
892- Description: Whether or not to show Git file status in tab.
893- Setting: `git_status`
894- Default: `false`
895
896### Activate on close
897
898- Description: What to do after closing the current tab.
899- Setting: `activate_on_close`
900- Default: `history`
901
902**Options**
903
9041. Activate the tab that was open previously:
905
906```json
907{
908 "activate_on_close": "history"
909}
910```
911
9122. Activate the right neighbour tab if present:
913
914```json
915{
916 "activate_on_close": "neighbour"
917}
918```
919
9203. Activate the left neighbour tab if present:
921
922```json
923{
924 "activate_on_close": "left_neighbour"
925}
926```
927
928### Show close button
929
930- Description: Controls the appearance behavior of the tab's close button.
931- Setting: `show_close_button`
932- Default: `hover`
933
934**Options**
935
9361. Show it just upon hovering the tab:
937
938```json
939{
940 "show_close_button": "hover"
941}
942```
943
9442. Show it persistently:
945
946```json
947{
948 "show_close_button": "always"
949}
950```
951
9523. Never show it, even if hovering it:
953
954```json
955{
956 "show_close_button": "hidden"
957}
958```
959
960### Show Diagnostics
961
962- Description: Whether to show diagnostics indicators in tabs. This setting only works when file icons are active and controls which files with diagnostic issues to mark.
963- Setting: `show_diagnostics`
964- Default: `off`
965
966**Options**
967
9681. Do not mark any files:
969
970```json
971{
972 "show_diagnostics": "off"
973}
974```
975
9762. Only mark files with errors:
977
978```json
979{
980 "show_diagnostics": "errors"
981}
982```
983
9843. Mark files with errors and warnings:
985
986```json
987{
988 "show_diagnostics": "all"
989}
990```
991
992## Editor Toolbar
993
994- Description: Whether or not to show various elements in the editor toolbar.
995- Setting: `toolbar`
996- Default:
997
998```json
999"toolbar": {
1000 "breadcrumbs": true,
1001 "quick_actions": true,
1002 "selections_menu": true
1003},
1004```
1005
1006**Options**
1007
1008Each option controls displaying of a particular toolbar element. If all elements are hidden, the editor toolbar is not displayed.
1009
1010## Enable Language Server
1011
1012- Description: Whether or not to use language servers to provide code intelligence.
1013- Setting: `enable_language_server`
1014- Default: `true`
1015
1016**Options**
1017
1018`boolean` values
1019
1020## Ensure Final Newline On Save
1021
1022- Description: Removes any lines containing only whitespace at the end of the file and ensures just one newline at the end.
1023- Setting: `ensure_final_newline_on_save`
1024- Default: `true`
1025
1026**Options**
1027
1028`boolean` values
1029
1030## LSP
1031
1032- Description: Configuration for language servers.
1033- Setting: `lsp`
1034- Default: `null`
1035
1036**Options**
1037
1038The following settings can be overridden for specific language servers:
1039
1040- `initialization_options`
1041- `settings`
1042
1043To override configuration for a language server, add an entry for that language server's name to the `lsp` value.
1044
1045Some options are passed via `initialization_options` to the language server. These are for options which must be specified at language server startup and when changed will require restarting the language server.
1046
1047For example to pass the `check` option to `rust-analyzer`, use the following configuration:
1048
1049```json
1050"lsp": {
1051 "rust-analyzer": {
1052 "initialization_options": {
1053 "check": {
1054 "command": "clippy" // rust-analyzer.check.command (default: "check")
1055 }
1056 }
1057 }
1058}
1059```
1060
1061While other options may be changed at a runtime and should be placed under `settings`:
1062
1063```json
1064"lsp": {
1065 "yaml-language-server": {
1066 "settings": {
1067 "yaml": {
1068 "keyOrdering": true // Enforces alphabetical ordering of keys in maps
1069 }
1070 }
1071 }
1072}
1073```
1074
1075## LSP Highlight Debounce
1076
1077- Description: The debounce delay in milliseconds before querying highlights from the language server based on the current cursor location.
1078- Setting: `lsp_highlight_debounce`
1079- Default: `75`
1080
1081**Options**
1082
1083`integer` values representing milliseconds
1084
1085## Format On Save
1086
1087- Description: Whether or not to perform a buffer format before saving.
1088- Setting: `format_on_save`
1089- Default: `on`
1090
1091**Options**
1092
10931. `on`, enables format on save obeying `formatter` setting:
1094
1095```json
1096{
1097 "format_on_save": "on"
1098}
1099```
1100
11012. `off`, disables format on save:
1102
1103```json
1104{
1105 "format_on_save": "off"
1106}
1107```
1108
1109## Formatter
1110
1111- Description: How to perform a buffer format.
1112- Setting: `formatter`
1113- Default: `auto`
1114
1115**Options**
1116
11171. To use the current language server, use `"language_server"`:
1118
1119```json
1120{
1121 "formatter": "language_server"
1122}
1123```
1124
11252. Or to use an external command, use `"external"`. Specify the name of the formatting program to run, and an array of arguments to pass to the program. The buffer's text will be passed to the program on stdin, and the formatted output should be written to stdout. For example, the following command would strip trailing spaces using [`sed(1)`](https://linux.die.net/man/1/sed):
1126
1127```json
1128{
1129 "formatter": {
1130 "external": {
1131 "command": "sed",
1132 "arguments": ["-e", "s/ *$//"]
1133 }
1134 }
1135}
1136```
1137
11383. External formatters may optionally include a `{buffer_path}` placeholder which at runtime will include the path of the buffer being formatted. Formatters operate by receiving file content via standard input, reformatting it and then outputting it to standard output and so normally don't know the filename of what they are formatting. Tools like prettier support receiving the file path via a command line argument which can then used to impact formatting decisions.
1139
1140WARNING: `{buffer_path}` should not be used to direct your formatter to read from a filename. Your formatter should only read from standard input and should not read or write files directly.
1141
1142```json
1143 "formatter": {
1144 "external": {
1145 "command": "prettier",
1146 "arguments": ["--stdin-filepath", "{buffer_path}"]
1147 }
1148 }
1149```
1150
11514. Or to use code actions provided by the connected language servers, use `"code_actions"`:
1152
1153```json
1154{
1155 "formatter": {
1156 "code_actions": {
1157 // Use ESLint's --fix:
1158 "source.fixAll.eslint": true,
1159 // Organize imports on save:
1160 "source.organizeImports": true
1161 }
1162 }
1163}
1164```
1165
11665. Or to use multiple formatters consecutively, use an array of formatters:
1167
1168```json
1169{
1170 "formatter": [
1171 { "language_server": { "name": "rust-analyzer" } },
1172 {
1173 "external": {
1174 "command": "sed",
1175 "arguments": ["-e", "s/ *$//"]
1176 }
1177 }
1178 ]
1179}
1180```
1181
1182Here `rust-analyzer` will be used first to format the code, followed by a call of sed.
1183If any of the formatters fails, the subsequent ones will still be executed.
1184
1185## Code Actions On Format
1186
1187- Description: The code actions to perform with the primary language server when formatting the buffer.
1188- Setting: `code_actions_on_format`
1189- Default: `{}`, except for Go it's `{ "source.organizeImports": true }`
1190
1191**Examples**
1192
1193<!--
1194TBD: Add Python Ruff source.organizeImports example
1195-->
1196
11971. Organize imports on format in TypeScript and TSX buffers:
1198
1199```json
1200{
1201 "languages": {
1202 "TypeScript": {
1203 "code_actions_on_format": {
1204 "source.organizeImports": true
1205 }
1206 },
1207 "TSX": {
1208 "code_actions_on_format": {
1209 "source.organizeImports": true
1210 }
1211 }
1212 }
1213}
1214```
1215
12162. Run ESLint `fixAll` code action when formatting:
1217
1218```json
1219{
1220 "languages": {
1221 "JavaScript": {
1222 "code_actions_on_format": {
1223 "source.fixAll.eslint": true
1224 }
1225 }
1226 }
1227}
1228```
1229
12303. Run only a single ESLint rule when using `fixAll`:
1231
1232```json
1233{
1234 "languages": {
1235 "JavaScript": {
1236 "code_actions_on_format": {
1237 "source.fixAll.eslint": true
1238 }
1239 }
1240 },
1241 "lsp": {
1242 "eslint": {
1243 "settings": {
1244 "codeActionOnSave": {
1245 "rules": ["import/order"]
1246 }
1247 }
1248 }
1249 }
1250}
1251```
1252
1253## Auto close
1254
1255- Description: Whether to automatically add matching closing characters when typing opening parenthesis, bracket, brace, single or double quote characters.
1256- Setting: `use_autoclose`
1257- Default: `true`
1258
1259**Options**
1260
1261`boolean` values
1262
1263## Always Treat Brackets As Autoclosed
1264
1265- Description: Controls how the editor handles the autoclosed characters.
1266- Setting: `always_treat_brackets_as_autoclosed`
1267- Default: `false`
1268
1269**Options**
1270
1271`boolean` values
1272
1273**Example**
1274
1275If the setting is set to `true`:
1276
12771. Enter in the editor: `)))`
12782. Move the cursor to the start: `^)))`
12793. Enter again: `)))`
1280
1281The result is still `)))` and not `))))))`, which is what it would be by default.
1282
1283## File Scan Exclusions
1284
1285- Setting: `file_scan_exclusions`
1286- Description: Files or globs of files that will be excluded by Zed entirely. They will be skipped during file scans, file searches, and not be displayed in the project file tree. Overrides `file_scan_inclusions`.
1287- Default:
1288
1289```json
1290"file_scan_exclusions": [
1291 "**/.git",
1292 "**/.svn",
1293 "**/.hg",
1294 "**/.jj",
1295 "**/CVS",
1296 "**/.DS_Store",
1297 "**/Thumbs.db",
1298 "**/.classpath",
1299 "**/.settings"
1300],
1301```
1302
1303Note, specifying `file_scan_exclusions` in settings.json will override the defaults (shown above). If you are looking to exclude additional items you will need to include all the default values in your settings.
1304
1305## File Scan Inclusions
1306
1307- Setting: `file_scan_inclusions`
1308- Description: Files or globs of files that will be included by Zed, even when ignored by git. This is useful for files that are not tracked by git, but are still important to your project. Note that globs that are overly broad can slow down Zed's file scanning. `file_scan_exclusions` takes precedence over these inclusions.
1309- Default:
1310
1311```json
1312"file_scan_inclusions": [".env*"],
1313```
1314
1315## File Types
1316
1317- Setting: `file_types`
1318- Description: Configure how Zed selects a language for a file based on its filename or extension. Supports glob entries.
1319- Default:
1320
1321```json
1322"file_types": {
1323 "JSONC": ["**/.zed/**/*.json", "**/zed/**/*.json", "**/Zed/**/*.json", "**/.vscode/**/*.json"],
1324 "Shell Script": [".env.*"]
1325}
1326```
1327
1328**Examples**
1329
1330To interpret all `.c` files as C++, files called `MyLockFile` as TOML and files starting with `Dockerfile` as Dockerfile:
1331
1332```json
1333{
1334 "file_types": {
1335 "C++": ["c"],
1336 "TOML": ["MyLockFile"],
1337 "Dockerfile": ["Dockerfile*"]
1338 }
1339}
1340```
1341
1342## Diagnostics
1343
1344- Description: Configuration for diagnostics-related features.
1345- Setting: `diagnostics`
1346- Default:
1347
1348```json
1349{
1350 "diagnostics": {
1351 "include_warnings": true,
1352 "inline": {
1353 "enabled": false
1354 },
1355 "update_with_cursor": false,
1356 "primary_only": false,
1357 "use_rendered": false
1358 }
1359}
1360```
1361
1362### Inline Diagnostics
1363
1364- Description: Whether or not to show diagnostics information inline.
1365- Setting: `inline`
1366- Default:
1367
1368```json
1369{
1370 "diagnostics": {
1371 "inline": {
1372 "enabled": false,
1373 "update_debounce_ms": 150,
1374 "padding": 4,
1375 "min_column": 0,
1376 "max_severity": null
1377 }
1378 }
1379}
1380```
1381
1382**Options**
1383
13841. Enable inline diagnostics.
1385
1386```json
1387{
1388 "diagnostics": {
1389 "inline": {
1390 "enabled": true
1391 }
1392 }
1393}
1394```
1395
13962. Delay diagnostic updates until some time after the last diagnostic update.
1397
1398```json
1399{
1400 "diagnostics": {
1401 "inline": {
1402 "enabled": true,
1403 "update_debounce_ms": 150
1404 }
1405 }
1406}
1407```
1408
14093. Set padding between the end of the source line and the start of the diagnostic.
1410
1411```json
1412{
1413 "diagnostics": {
1414 "inline": {
1415 "enabled": true,
1416 "padding": 4
1417 }
1418 }
1419}
1420```
1421
14224. Horizontally align inline diagnostics at the given column.
1423
1424```json
1425{
1426 "diagnostics": {
1427 "inline": {
1428 "enabled": true,
1429 "min_column": 80
1430 }
1431 }
1432}
1433```
1434
14355. Show only warning and error diagnostics.
1436
1437```json
1438{
1439 "diagnostics": {
1440 "inline": {
1441 "enabled": true,
1442 "max_severity": "warning"
1443 }
1444 }
1445}
1446```
1447
1448## Git
1449
1450- Description: Configuration for git-related features.
1451- Setting: `git`
1452- Default:
1453
1454```json
1455{
1456 "git": {
1457 "git_gutter": "tracked_files",
1458 "inline_blame": {
1459 "enabled": true
1460 },
1461 "hunk_style": "staged_hollow"
1462 }
1463}
1464```
1465
1466### Git Gutter
1467
1468- Description: Whether or not to show the git gutter.
1469- Setting: `git_gutter`
1470- Default: `tracked_files`
1471
1472**Options**
1473
14741. Show git gutter in tracked files
1475
1476```json
1477{
1478 "git": {
1479 "git_gutter": "tracked_files"
1480 }
1481}
1482```
1483
14842. Hide git gutter
1485
1486```json
1487{
1488 "git": {
1489 "git_gutter": "hide"
1490 }
1491}
1492```
1493
1494### Gutter Debounce
1495
1496- Description: Sets the debounce threshold (in milliseconds) after which changes are reflected in the git gutter.
1497- Setting: `gutter_debounce`
1498- Default: `null`
1499
1500**Options**
1501
1502`integer` values representing milliseconds
1503
1504Example:
1505
1506```json
1507{
1508 "git": {
1509 "gutter_debounce": 100
1510 }
1511}
1512```
1513
1514### Inline Git Blame
1515
1516- Description: Whether or not to show git blame information inline, on the currently focused line.
1517- Setting: `inline_blame`
1518- Default:
1519
1520```json
1521{
1522 "git": {
1523 "inline_blame": {
1524 "enabled": true
1525 }
1526 }
1527}
1528```
1529
1530### Hunk Style
1531
1532- Description: What styling we should use for the diff hunks.
1533- Setting: `hunk_style`
1534- Default:
1535
1536```json
1537{
1538 "git": {
1539 "hunk_style": "staged_hollow"
1540 }
1541}
1542```
1543
1544**Options**
1545
15461. Show the staged hunks faded out and with a border:
1547
1548```json
1549{
1550 "git": {
1551 "hunk_style": "staged_hollow"
1552 }
1553}
1554```
1555
15562. Show unstaged hunks faded out and with a border:
1557
1558```json
1559{
1560 "git": {
1561 "hunk_style": "unstaged_hollow"
1562 }
1563}
1564```
1565
1566**Options**
1567
15681. Disable inline git blame:
1569
1570```json
1571{
1572 "git": {
1573 "inline_blame": {
1574 "enabled": false
1575 }
1576 }
1577}
1578```
1579
15802. Only show inline git blame after a delay (that starts after cursor stops moving):
1581
1582```json
1583{
1584 "git": {
1585 "inline_blame": {
1586 "enabled": true,
1587 "delay_ms": 500
1588 }
1589 }
1590}
1591```
1592
15933. Show a commit summary next to the commit date and author:
1594
1595```json
1596{
1597 "git": {
1598 "inline_blame": {
1599 "enabled": true,
1600 "show_commit_summary": true
1601 }
1602 }
1603}
1604```
1605
16064. Use this as the minimum column at which to display inline blame information:
1607
1608```json
1609{
1610 "git": {
1611 "inline_blame": {
1612 "enabled": true,
1613 "min_column": 80
1614 }
1615 }
1616}
1617```
1618
1619## Indent Guides
1620
1621- Description: Configuration related to indent guides. Indent guides can be configured separately for each language.
1622- Setting: `indent_guides`
1623- Default:
1624
1625```json
1626{
1627 "indent_guides": {
1628 "enabled": true,
1629 "line_width": 1,
1630 "active_line_width": 1,
1631 "coloring": "fixed",
1632 "background_coloring": "disabled"
1633 }
1634}
1635```
1636
1637**Options**
1638
16391. Disable indent guides
1640
1641```json
1642{
1643 "indent_guides": {
1644 "enabled": false
1645 }
1646}
1647```
1648
16492. Enable indent guides for a specific language.
1650
1651```json
1652{
1653 "languages": {
1654 "Python": {
1655 "indent_guides": {
1656 "enabled": true
1657 }
1658 }
1659 }
1660}
1661```
1662
16633. Enable indent aware coloring ("rainbow indentation").
1664 The colors that are used for different indentation levels are defined in the theme (theme key: `accents`). They can be customized by using theme overrides.
1665
1666```json
1667{
1668 "indent_guides": {
1669 "enabled": true,
1670 "coloring": "indent_aware"
1671 }
1672}
1673```
1674
16754. Enable indent aware background coloring ("rainbow indentation").
1676 The colors that are used for different indentation levels are defined in the theme (theme key: `accents`). They can be customized by using theme overrides.
1677
1678```json
1679{
1680 "indent_guides": {
1681 "enabled": true,
1682 "coloring": "indent_aware",
1683 "background_coloring": "indent_aware"
1684 }
1685}
1686```
1687
1688## Hard Tabs
1689
1690- Description: Whether to indent lines using tab characters or multiple spaces.
1691- Setting: `hard_tabs`
1692- Default: `false`
1693
1694**Options**
1695
1696`boolean` values
1697
1698## Hover Popover Enabled
1699
1700- Description: Whether or not to show the informational hover box when moving the mouse over symbols in the editor.
1701- Setting: `hover_popover_enabled`
1702- Default: `true`
1703
1704**Options**
1705
1706`boolean` values
1707
1708## Icon Theme
1709
1710- Description: The icon theme setting can be specified in two forms - either as the name of an icon theme or as an object containing the `mode`, `dark`, and `light` icon themes for files/folders inside Zed.
1711- Setting: `icon_theme`
1712- Default: `Zed (Default)`
1713
1714### Icon Theme Object
1715
1716- Description: Specify the icon theme using an object that includes the `mode`, `dark`, and `light`.
1717- Setting: `icon_theme`
1718- Default:
1719
1720```json
1721"icon_theme": {
1722 "mode": "system",
1723 "dark": "Zed (Default)",
1724 "light": "Zed (Default)"
1725},
1726```
1727
1728### Mode
1729
1730- Description: Specify the icon theme mode.
1731- Setting: `mode`
1732- Default: `system`
1733
1734**Options**
1735
17361. Set the icon theme to dark mode
1737
1738```json
1739{
1740 "mode": "dark"
1741}
1742```
1743
17442. Set the icon theme to light mode
1745
1746```json
1747{
1748 "mode": "light"
1749}
1750```
1751
17523. Set the icon theme to system mode
1753
1754```json
1755{
1756 "mode": "system"
1757}
1758```
1759
1760### Dark
1761
1762- Description: The name of the dark icon theme.
1763- Setting: `dark`
1764- Default: `Zed (Default)`
1765
1766**Options**
1767
1768Run the `icon theme selector: toggle` action in the command palette to see a current list of valid icon themes names.
1769
1770### Light
1771
1772- Description: The name of the light icon theme.
1773- Setting: `light`
1774- Default: `Zed (Default)`
1775
1776**Options**
1777
1778Run the `icon theme selector: toggle` action in the command palette to see a current list of valid icon themes names.
1779
1780## Inlay hints
1781
1782- Description: Configuration for displaying extra text with hints in the editor.
1783- Setting: `inlay_hints`
1784- Default:
1785
1786```json
1787"inlay_hints": {
1788 "enabled": false,
1789 "show_type_hints": true,
1790 "show_parameter_hints": true,
1791 "show_other_hints": true,
1792 "show_background": false,
1793 "edit_debounce_ms": 700,
1794 "scroll_debounce_ms": 50,
1795 "toggle_on_modifiers_press": null
1796}
1797```
1798
1799**Options**
1800
1801Inlay hints querying consists of two parts: editor (client) and LSP server.
1802With the inlay settings above are changed to enable the hints, editor will start to query certain types of hints and react on LSP hint refresh request from the server.
1803At this point, the server may or may not return hints depending on its implementation, further configuration might be needed, refer to the corresponding LSP server documentation.
1804
1805The following languages have inlay hints preconfigured by Zed:
1806
1807- [Go](https://docs.zed.dev/languages/go)
1808- [Rust](https://docs.zed.dev/languages/rust)
1809- [Svelte](https://docs.zed.dev/languages/svelte)
1810- [Typescript](https://docs.zed.dev/languages/typescript)
1811
1812Use the `lsp` section for the server configuration. Examples are provided in the corresponding language documentation.
1813
1814Hints are not instantly queried in Zed, two kinds of debounces are used, either may be set to 0 to be disabled.
1815Settings-related hint updates are not debounced.
1816
1817All possible config values for `toggle_on_modifiers_press` are:
1818
1819```json
1820"inlay_hints": {
1821 "toggle_on_modifiers_press": {
1822 "control": true,
1823 "shift": true,
1824 "alt": true,
1825 "platform": true,
1826 "function": true
1827 }
1828}
1829```
1830
1831Unspecified values have a `false` value, hints won't be toggled if all the modifiers are `false` or not all the modifiers are pressed.
1832
1833## Journal
1834
1835- Description: Configuration for the journal.
1836- Setting: `journal`
1837- Default:
1838
1839```json
1840"journal": {
1841 "path": "~",
1842 "hour_format": "hour12"
1843}
1844```
1845
1846### Path
1847
1848- Description: The path of the directory where journal entries are stored.
1849- Setting: `path`
1850- Default: `~`
1851
1852**Options**
1853
1854`string` values
1855
1856### Hour Format
1857
1858- Description: The format to use for displaying hours in the journal.
1859- Setting: `hour_format`
1860- Default: `hour12`
1861
1862**Options**
1863
18641. 12-hour format:
1865
1866```json
1867{
1868 "hour_format": "hour12"
1869}
1870```
1871
18722. 24-hour format:
1873
1874```json
1875{
1876 "hour_format": "hour24"
1877}
1878```
1879
1880## Languages
1881
1882- Description: Configuration for specific languages.
1883- Setting: `languages`
1884- Default: `null`
1885
1886**Options**
1887
1888To override settings for a language, add an entry for that languages name to the `languages` value. Example:
1889
1890```json
1891"languages": {
1892 "C": {
1893 "format_on_save": "off",
1894 "preferred_line_length": 64,
1895 "soft_wrap": "preferred_line_length"
1896 },
1897 "JSON": {
1898 "tab_size": 4
1899 }
1900}
1901```
1902
1903The following settings can be overridden for each specific language:
1904
1905- [`enable_language_server`](#enable-language-server)
1906- [`ensure_final_newline_on_save`](#ensure-final-newline-on-save)
1907- [`format_on_save`](#format-on-save)
1908- [`formatter`](#formatter)
1909- [`hard_tabs`](#hard-tabs)
1910- [`preferred_line_length`](#preferred-line-length)
1911- [`remove_trailing_whitespace_on_save`](#remove-trailing-whitespace-on-save)
1912- [`show_edit_predictions`](#show-edit-predictions)
1913- [`show_whitespaces`](#show-whitespaces)
1914- [`soft_wrap`](#soft-wrap)
1915- [`tab_size`](#tab-size)
1916- [`use_autoclose`](#use-autoclose)
1917- [`always_treat_brackets_as_autoclosed`](#always-treat-brackets-as-autoclosed)
1918
1919These values take in the same options as the root-level settings with the same name.
1920
1921## Network Proxy
1922
1923- Description: Configure a network proxy for Zed.
1924- Setting: `proxy`
1925- Default: `null`
1926
1927**Options**
1928
1929The proxy setting must contain a URL to the proxy.
1930
1931The following URI schemes are supported:
1932
1933- `http`
1934- `https`
1935- `socks4` - SOCKS4 proxy with local DNS
1936- `socks4a` - SOCKS4 proxy with remote DNS
1937- `socks5` - SOCKS5 proxy with local DNS
1938- `socks5h` - SOCKS5 proxy with remote DNS
1939
1940`http` will be used when no scheme is specified.
1941
1942By default no proxy will be used, or Zed will attempt to retrieve proxy settings from environment variables, such as `http_proxy`, `HTTP_PROXY`, `https_proxy`, `HTTPS_PROXY`, `all_proxy`, `ALL_PROXY`.
1943
1944For example, to set an `http` proxy, add the following to your settings:
1945
1946```json
1947{
1948 "proxy": "http://127.0.0.1:10809"
1949}
1950```
1951
1952Or to set a `socks5` proxy:
1953
1954```json
1955{
1956 "proxy": "socks5h://localhost:10808"
1957}
1958```
1959
1960## Preview tabs
1961
1962- Description:
1963 Preview tabs allow you to open files in preview mode, where they close automatically when you switch to another file unless you explicitly pin them. This is useful for quickly viewing files without cluttering your workspace. Preview tabs display their file names in italics. \
1964 There are several ways to convert a preview tab into a regular tab:
1965
1966 - Double-clicking on the file
1967 - Double-clicking on the tab header
1968 - Using the `project_panel::OpenPermanent` action
1969 - Editing the file
1970 - Dragging the file to a different pane
1971
1972- Setting: `preview_tabs`
1973- Default:
1974
1975```json
1976"preview_tabs": {
1977 "enabled": true,
1978 "enable_preview_from_file_finder": false,
1979 "enable_preview_from_code_navigation": false,
1980}
1981```
1982
1983### Enable preview from file finder
1984
1985- Description: Determines whether to open files in preview mode when selected from the file finder.
1986- Setting: `enable_preview_from_file_finder`
1987- Default: `false`
1988
1989**Options**
1990
1991`boolean` values
1992
1993### Enable preview from code navigation
1994
1995- Description: Determines whether a preview tab gets replaced when code navigation is used to navigate away from the tab.
1996- Setting: `enable_preview_from_code_navigation`
1997- Default: `false`
1998
1999**Options**
2000
2001`boolean` values
2002
2003## File Finder
2004
2005### Modal Max Width
2006
2007- Description: Max-width of the file finder modal. It can take one of these values: `small`, `medium`, `large`, `xlarge`, and `full`.
2008- Setting: `modal_max_width`
2009- Default: `small`
2010
2011## Preferred Line Length
2012
2013- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
2014- Setting: `preferred_line_length`
2015- Default: `80`
2016
2017**Options**
2018
2019`integer` values
2020
2021## Projects Online By Default
2022
2023- Description: Whether or not to show the online projects view by default.
2024- Setting: `projects_online_by_default`
2025- Default: `true`
2026
2027**Options**
2028
2029`boolean` values
2030
2031## Remove Trailing Whitespace On Save
2032
2033- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
2034- Setting: `remove_trailing_whitespace_on_save`
2035- Default: `true`
2036
2037**Options**
2038
2039`boolean` values
2040
2041## Search
2042
2043- Description: Search options to enable by default when opening new project and buffer searches.
2044- Setting: `search`
2045- Default:
2046
2047```json
2048"search": {
2049 "whole_word": false,
2050 "case_sensitive": false,
2051 "include_ignored": false,
2052 "regex": false
2053},
2054```
2055
2056## Seed Search Query From Cursor
2057
2058- Description: When to populate a new search's query based on the text under the cursor.
2059- Setting: `seed_search_query_from_cursor`
2060- Default: `always`
2061
2062**Options**
2063
20641. `always` always populate the search query with the word under the cursor
20652. `selection` only populate the search query when there is text selected
20663. `never` never populate the search query
2067
2068## Use Smartcase Search
2069
2070- Description: When enabled, automatically adjusts search case sensitivity based on your query. If your search query contains any uppercase letters, the search becomes case-sensitive; if it contains only lowercase letters, the search becomes case-insensitive. \
2071 This applies to both in-file searches and project-wide searches.
2072- Setting: `use_smartcase_search`
2073- Default: `false`
2074
2075**Options**
2076
2077`boolean` values
2078
2079Examples:
2080
2081- Searching for "function" would match "function", "Function", "FUNCTION", etc.
2082- Searching for "Function" would only match "Function", not "function" or "FUNCTION"
2083
2084## Show Call Status Icon
2085
2086- Description: Whether or not to show the call status icon in the status bar.
2087- Setting: `show_call_status_icon`
2088- Default: `true`
2089
2090**Options**
2091
2092`boolean` values
2093
2094## Completions
2095
2096- Description: Controls how completions are processed for this language.
2097- Setting: `completions`
2098- Default:
2099
2100```json
2101{
2102 "completions": {
2103 "words": "fallback",
2104 "lsp": true,
2105 "lsp_fetch_timeout_ms": 0,
2106 "lsp_insert_mode": "replace_suffix"
2107 }
2108}
2109```
2110
2111### Words
2112
2113- Description: Controls how words are completed. For large documents, not all words may be fetched for completion.
2114- Setting: `words`
2115- Default: `fallback`
2116
2117**Options**
2118
21191. `enabled` - Always fetch document's words for completions along with LSP completions
21202. `fallback` - Only if LSP response errors or times out, use document's words to show completions
21213. `disabled` - Never fetch or complete document's words for completions (word-based completions can still be queried via a separate action)
2122
2123### LSP
2124
2125- Description: Whether to fetch LSP completions or not.
2126- Setting: `lsp`
2127- Default: `true`
2128
2129**Options**
2130
2131`boolean` values
2132
2133### LSP Fetch Timeout (ms)
2134
2135- Description: When fetching LSP completions, determines how long to wait for a response of a particular server. When set to 0, waits indefinitely.
2136- Setting: `lsp_fetch_timeout_ms`
2137- Default: `0`
2138
2139**Options**
2140
2141`integer` values representing milliseconds
2142
2143### LSP Insert Mode
2144
2145- Description: Controls what range to replace when accepting LSP completions.
2146- Setting: `lsp_insert_mode`
2147- Default: `replace_suffix`
2148
2149**Options**
2150
21511. `insert` - Replaces text before the cursor, using the `insert` range described in the LSP specification
21522. `replace` - Replaces text before and after the cursor, using the `replace` range described in the LSP specification
21533. `replace_subsequence` - Behaves like `"replace"` if the text that would be replaced is a subsequence of the completion text, and like `"insert"` otherwise
21544. `replace_suffix` - Behaves like `"replace"` if the text after the cursor is a suffix of the completion, and like `"insert"` otherwise
2155
2156## Show Completions On Input
2157
2158- Description: Whether or not to show completions as you type.
2159- Setting: `show_completions_on_input`
2160- Default: `true`
2161
2162**Options**
2163
2164`boolean` values
2165
2166## Show Completion Documentation
2167
2168- Description: Whether to display inline and alongside documentation for items in the completions menu.
2169- Setting: `show_completion_documentation`
2170- Default: `true`
2171
2172**Options**
2173
2174`boolean` values
2175
2176## Show Edit Predictions
2177
2178- Description: Whether to show edit predictions as you type or manually by triggering `editor::ShowEditPrediction`.
2179- Setting: `show_edit_predictions`
2180- Default: `true`
2181
2182**Options**
2183
2184`boolean` values
2185
2186## Show Whitespaces
2187
2188- Description: Whether or not to show render whitespace characters in the editor.
2189- Setting: `show_whitespaces`
2190- Default: `selection`
2191
2192**Options**
2193
21941. `all`
21952. `selection`
21963. `none`
21974. `boundary`
2198
2199## Soft Wrap
2200
2201- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
2202- Setting: `soft_wrap`
2203- Default: `none`
2204
2205**Options**
2206
22071. `none` to avoid wrapping generally, unless the line is too long
22082. `prefer_line` (deprecated, same as `none`)
22093. `editor_width` to wrap lines that overflow the editor width
22104. `preferred_line_length` to wrap lines that overflow `preferred_line_length` config value
22115. `bounded` to wrap lines at the minimum of `editor_width` and `preferred_line_length`
2212
2213## Wrap Guides (Vertical Rulers)
2214
2215- Description: Where to display vertical rulers as wrap-guides. Disable by setting `show_wrap_guides` to `false`.
2216- Setting: `wrap_guides`
2217- Default: []
2218
2219**Options**
2220
2221List of `integer` column numbers
2222
2223## Tab Size
2224
2225- Description: The number of spaces to use for each tab character.
2226- Setting: `tab_size`
2227- Default: `4`
2228
2229**Options**
2230
2231`integer` values
2232
2233## Telemetry
2234
2235- Description: Control what info is collected by Zed.
2236- Setting: `telemetry`
2237- Default:
2238
2239```json
2240"telemetry": {
2241 "diagnostics": true,
2242 "metrics": true
2243},
2244```
2245
2246**Options**
2247
2248### Diagnostics
2249
2250- Description: Setting for sending debug-related data, such as crash reports.
2251- Setting: `diagnostics`
2252- Default: `true`
2253
2254**Options**
2255
2256`boolean` values
2257
2258### Metrics
2259
2260- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
2261- Setting: `metrics`
2262- Default: `true`
2263
2264**Options**
2265
2266`boolean` values
2267
2268## Terminal
2269
2270- Description: Configuration for the terminal.
2271- Setting: `terminal`
2272- Default:
2273
2274```json
2275{
2276 "terminal": {
2277 "alternate_scroll": "off",
2278 "blinking": "terminal_controlled",
2279 "copy_on_select": false,
2280 "dock": "bottom",
2281 "default_width": 640,
2282 "default_height": 320,
2283 "detect_venv": {
2284 "on": {
2285 "directories": [".env", "env", ".venv", "venv"],
2286 "activate_script": "default"
2287 }
2288 },
2289 "env": {},
2290 "font_family": null,
2291 "font_features": null,
2292 "font_size": null,
2293 "line_height": "comfortable",
2294 "option_as_meta": false,
2295 "button": true,
2296 "shell": "system",
2297 "toolbar": {
2298 "breadcrumbs": true
2299 },
2300 "working_directory": "current_project_directory",
2301 "scrollbar": {
2302 "show": null
2303 }
2304 }
2305}
2306```
2307
2308### Terminal: Dock
2309
2310- Description: Control the position of the dock
2311- Setting: `dock`
2312- Default: `bottom`
2313
2314**Options**
2315
2316`"bottom"`, `"left"` or `"right"`
2317
2318### Terminal: Alternate Scroll
2319
2320- Description: Set whether Alternate Scroll mode (DECSET code: `?1007`) is active by default. Alternate Scroll mode converts mouse scroll events into up / down key presses when in the alternate screen (e.g. when running applications like vim or less). The terminal can still set and unset this mode with ANSI escape codes.
2321- Setting: `alternate_scroll`
2322- Default: `off`
2323
2324**Options**
2325
23261. Default alternate scroll mode to off
2327
2328```json
2329{
2330 "terminal": {
2331 "alternate_scroll": "off"
2332 }
2333}
2334```
2335
23362. Default alternate scroll mode to on
2337
2338```json
2339{
2340 "terminal": {
2341 "alternate_scroll": "on"
2342 }
2343}
2344```
2345
2346### Terminal: Blinking
2347
2348- Description: Set the cursor blinking behavior in the terminal
2349- Setting: `blinking`
2350- Default: `terminal_controlled`
2351
2352**Options**
2353
23541. Never blink the cursor, ignore the terminal mode
2355
2356```json
2357{
2358 "terminal": {
2359 "blinking": "off"
2360 }
2361}
2362```
2363
23642. Default the cursor blink to off, but allow the terminal to turn blinking on
2365
2366```json
2367{
2368 "terminal": {
2369 "blinking": "terminal_controlled"
2370 }
2371}
2372```
2373
23743. Always blink the cursor, ignore the terminal mode
2375
2376```json
2377{
2378 "terminal": {
2379 "blinking": "on"
2380 }
2381}
2382```
2383
2384### Terminal: Copy On Select
2385
2386- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
2387- Setting: `copy_on_select`
2388- Default: `false`
2389
2390**Options**
2391
2392`boolean` values
2393
2394**Example**
2395
2396```json
2397{
2398 "terminal": {
2399 "copy_on_select": true
2400 }
2401}
2402```
2403
2404### Terminal: Env
2405
2406- Description: Any key-value pairs added to this object will be added to the terminal's environment. Keys must be unique, use `:` to separate multiple values in a single variable
2407- Setting: `env`
2408- Default: `{}`
2409
2410**Example**
2411
2412```json
2413{
2414 "terminal": {
2415 "env": {
2416 "ZED": "1",
2417 "KEY": "value1:value2"
2418 }
2419 }
2420}
2421```
2422
2423### Terminal: Font Size
2424
2425- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
2426- Setting: `font_size`
2427- Default: `null`
2428
2429**Options**
2430
2431`integer` values
2432
2433```json
2434{
2435 "terminal": {
2436 "font_size": 15
2437 }
2438}
2439```
2440
2441### Terminal: Font Family
2442
2443- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
2444- Setting: `font_family`
2445- Default: `null`
2446
2447**Options**
2448
2449The name of any font family installed on the user's system
2450
2451```json
2452{
2453 "terminal": {
2454 "font_family": "Berkeley Mono"
2455 }
2456}
2457```
2458
2459### Terminal: Font Features
2460
2461- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
2462- Setting: `font_features`
2463- Default: `null`
2464- Platform: macOS and Windows.
2465
2466**Options**
2467
2468See Buffer Font Features
2469
2470```json
2471{
2472 "terminal": {
2473 "font_features": {
2474 "calt": false
2475 // See Buffer Font Features for more features
2476 }
2477 }
2478}
2479```
2480
2481### Terminal: Line Height
2482
2483- Description: Set the terminal's line height.
2484- Setting: `line_height`
2485- Default: `comfortable`
2486
2487**Options**
2488
24891. Use a line height that's `comfortable` for reading, 1.618. (default)
2490
2491```json
2492{
2493 "terminal": {
2494 "line_height": "comfortable"
2495 }
2496}
2497```
2498
24992. Use a `standard` line height, 1.3. This option is useful for TUIs, particularly if they use box characters
2500
2501```json
2502{
2503 "terminal": {
2504 "line_height": "standard"
2505 }
2506}
2507```
2508
25093. Use a custom line height.
2510
2511```json
2512{
2513 "terminal": {
2514 "line_height": {
2515 "custom": 2
2516 }
2517 }
2518}
2519```
2520
2521### Terminal: Option As Meta
2522
2523- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
2524- Setting: `option_as_meta`
2525- Default: `false`
2526
2527**Options**
2528
2529`boolean` values
2530
2531```json
2532{
2533 "terminal": {
2534 "option_as_meta": true
2535 }
2536}
2537```
2538
2539### Terminal: Shell
2540
2541- Description: What shell to use when launching the terminal.
2542- Setting: `shell`
2543- Default: `system`
2544
2545**Options**
2546
25471. Use the system's default terminal configuration (usually the `/etc/passwd` file).
2548
2549```json
2550{
2551 "terminal": {
2552 "shell": "system"
2553 }
2554}
2555```
2556
25572. A program to launch:
2558
2559```json
2560{
2561 "terminal": {
2562 "shell": {
2563 "program": "sh"
2564 }
2565 }
2566}
2567```
2568
25693. A program with arguments:
2570
2571```json
2572{
2573 "terminal": {
2574 "shell": {
2575 "with_arguments": {
2576 "program": "/bin/bash",
2577 "args": ["--login"]
2578 }
2579 }
2580 }
2581}
2582```
2583
2584## Terminal: Detect Virtual Environments {#terminal-detect_venv}
2585
2586- Description: Activate the [Python Virtual Environment](https://docs.python.org/3/library/venv.html), if one is found, in the terminal's working directory (as resolved by the working_directory and automatically activating the virtual environment.
2587- Setting: `detect_venv`
2588- Default:
2589
2590```json
2591{
2592 "terminal": {
2593 "detect_venv": {
2594 "on": {
2595 // Default directories to search for virtual environments, relative
2596 // to the current working directory. We recommend overriding this
2597 // in your project's settings, rather than globally.
2598 "directories": [".env", "env", ".venv", "venv"],
2599 // Can also be `csh`, `fish`, and `nushell`
2600 "activate_script": "default"
2601 }
2602 }
2603 }
2604}
2605```
2606
2607Disable with:
2608
2609```json
2610{
2611 "terminal": {
2612 "detect_venv": "off"
2613 }
2614}
2615```
2616
2617## Terminal: Toolbar
2618
2619- Description: Whether or not to show various elements in the terminal toolbar.
2620- Setting: `toolbar`
2621- Default:
2622
2623```json
2624{
2625 "terminal": {
2626 "toolbar": {
2627 "breadcrumbs": true
2628 }
2629 }
2630}
2631```
2632
2633**Options**
2634
2635At the moment, only the `breadcrumbs` option is available, it controls displaying of the terminal title that can be changed via `PROMPT_COMMAND`.
2636
2637If the terminal title is empty, the breadcrumbs won't be shown.
2638
2639The shell running in the terminal needs to be configured to emit the title.
2640
2641Example command to set the title: `echo -e "\e]2;New Title\007";`
2642
2643### Terminal: Button
2644
2645- Description: Control to show or hide the terminal button in the status bar
2646- Setting: `button`
2647- Default: `true`
2648
2649**Options**
2650
2651`boolean` values
2652
2653```json
2654{
2655 "terminal": {
2656 "button": false
2657 }
2658}
2659```
2660
2661### Terminal: Working Directory
2662
2663- Description: What working directory to use when launching the terminal.
2664- Setting: `working_directory`
2665- Default: `"current_project_directory"`
2666
2667**Options**
2668
26691. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
2670
2671```json
2672{
2673 "terminal": {
2674 "working_directory": "current_project_directory"
2675 }
2676}
2677```
2678
26792. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
2680
2681```json
2682{
2683 "terminal": {
2684 "working_directory": "first_project_directory"
2685 }
2686}
2687```
2688
26893. Always use this platform's home directory (if we can find it)
2690
2691```json
2692{
2693 "terminal": {
2694 "working_directory": "always_home"
2695 }
2696}
2697```
2698
26994. Always use a specific directory. This value will be shell expanded. If this path is not a valid directory the terminal will default to this platform's home directory.
2700
2701```json
2702{
2703 "terminal": {
2704 "working_directory": {
2705 "always": {
2706 "directory": "~/zed/projects/"
2707 }
2708 }
2709 }
2710}
2711```
2712
2713## Theme
2714
2715- Description: The theme setting can be specified in two forms - either as the name of a theme or as an object containing the `mode`, `dark`, and `light` themes for the Zed UI.
2716- Setting: `theme`
2717- Default: `One Dark`
2718
2719### Theme Object
2720
2721- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
2722- Setting: `theme`
2723- Default:
2724
2725```json
2726"theme": {
2727 "mode": "system",
2728 "dark": "One Dark",
2729 "light": "One Light"
2730},
2731```
2732
2733### Mode
2734
2735- Description: Specify theme mode.
2736- Setting: `mode`
2737- Default: `system`
2738
2739**Options**
2740
27411. Set the theme to dark mode
2742
2743```json
2744{
2745 "mode": "dark"
2746}
2747```
2748
27492. Set the theme to light mode
2750
2751```json
2752{
2753 "mode": "light"
2754}
2755```
2756
27573. Set the theme to system mode
2758
2759```json
2760{
2761 "mode": "system"
2762}
2763```
2764
2765### Dark
2766
2767- Description: The name of the dark Zed theme to use for the UI.
2768- Setting: `dark`
2769- Default: `One Dark`
2770
2771**Options**
2772
2773Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
2774
2775### Light
2776
2777- Description: The name of the light Zed theme to use for the UI.
2778- Setting: `light`
2779- Default: `One Light`
2780
2781**Options**
2782
2783Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
2784
2785## Vim
2786
2787- Description: Whether or not to enable vim mode (work in progress).
2788- Setting: `vim_mode`
2789- Default: `false`
2790
2791## Project Panel
2792
2793- Description: Customize project panel
2794- Setting: `project_panel`
2795- Default:
2796
2797```json
2798{
2799 "project_panel": {
2800 "button": true,
2801 "default_width": 240,
2802 "dock": "left",
2803 "entry_spacing": "comfortable",
2804 "file_icons": true,
2805 "folder_icons": true,
2806 "git_status": true,
2807 "indent_size": 20,
2808 "auto_reveal_entries": true,
2809 "auto_fold_dirs": true,
2810 "scrollbar": {
2811 "show": null
2812 },
2813 "show_diagnostics": "all",
2814 "indent_guides": {
2815 "show": "always"
2816 }
2817 }
2818}
2819```
2820
2821### Dock
2822
2823- Description: Control the position of the dock
2824- Setting: `dock`
2825- Default: `left`
2826
2827**Options**
2828
28291. Default dock position to left
2830
2831```json
2832{
2833 "dock": "left"
2834}
2835```
2836
28372. Default dock position to right
2838
2839```json
2840{
2841 "dock": "right"
2842}
2843```
2844
2845### Entry Spacing
2846
2847- Description: Spacing between worktree entries
2848- Setting: `entry_spacing`
2849- Default: `comfortable`
2850
2851**Options**
2852
28531. Comfortable entry spacing
2854
2855```json
2856{
2857 "entry_spacing": "comfortable"
2858}
2859```
2860
28612. Standard entry spacing
2862
2863```json
2864{
2865 "entry_spacing": "standard"
2866}
2867```
2868
2869### Git Status
2870
2871- Description: Indicates newly created and updated files
2872- Setting: `git_status`
2873- Default: `true`
2874
2875**Options**
2876
28771. Default enable git status
2878
2879```json
2880{
2881 "git_status": true
2882}
2883```
2884
28852. Default disable git status
2886
2887```json
2888{
2889 "git_status": false
2890}
2891```
2892
2893### Default Width
2894
2895- Description: Customize default width taken by project panel
2896- Setting: `default_width`
2897- Default: `240`
2898
2899**Options**
2900
2901`float` values
2902
2903### Auto Reveal Entries
2904
2905- Description: Whether to reveal it in the project panel automatically, when a corresponding project entry becomes active. Gitignored entries are never auto revealed.
2906- Setting: `auto_reveal_entries`
2907- Default: `true`
2908
2909**Options**
2910
29111. Enable auto reveal entries
2912
2913```json
2914{
2915 "auto_reveal_entries": true
2916}
2917```
2918
29192. Disable auto reveal entries
2920
2921```json
2922{
2923 "auto_reveal_entries": false
2924}
2925```
2926
2927### Auto Fold Dirs
2928
2929- Description: Whether to fold directories automatically when directory has only one directory inside.
2930- Setting: `auto_fold_dirs`
2931- Default: `true`
2932
2933**Options**
2934
29351. Enable auto fold dirs
2936
2937```json
2938{
2939 "auto_fold_dirs": true
2940}
2941```
2942
29432. Disable auto fold dirs
2944
2945```json
2946{
2947 "auto_fold_dirs": false
2948}
2949```
2950
2951### Indent Size
2952
2953- Description: Amount of indentation (in pixels) for nested items.
2954- Setting: `indent_size`
2955- Default: `20`
2956
2957### Indent Guides: Show
2958
2959- Description: Whether to show indent guides in the project panel.
2960- Setting: `indent_guides`
2961- Default:
2962
2963```json
2964"indent_guides": {
2965 "show": "always"
2966}
2967```
2968
2969**Options**
2970
29711. Show indent guides in the project panel
2972
2973```json
2974{
2975 "indent_guides": {
2976 "show": "always"
2977 }
2978}
2979```
2980
29812. Hide indent guides in the project panel
2982
2983```json
2984{
2985 "indent_guides": {
2986 "show": "never"
2987 }
2988}
2989```
2990
2991### Scrollbar: Show
2992
2993- Description: Whether to show a scrollbar in the project panel. Possible values: null, "auto", "system", "always", "never". Inherits editor settings when absent, see its description for more details.
2994- Setting: `scrollbar`
2995- Default:
2996
2997```json
2998"scrollbar": {
2999 "show": null
3000}
3001```
3002
3003**Options**
3004
30051. Show scrollbar in the project panel
3006
3007```json
3008{
3009 "scrollbar": {
3010 "show": "always"
3011 }
3012}
3013```
3014
30152. Hide scrollbar in the project panel
3016
3017```json
3018{
3019 "scrollbar": {
3020 "show": "never"
3021 }
3022}
3023```
3024
3025## Assistant Panel
3026
3027- Description: Customize assistant panel
3028- Setting: `assistant`
3029- Default:
3030
3031```json
3032"assistant": {
3033 "version": "2",
3034 "enabled": true,
3035 "button": true,
3036 "dock": "right",
3037 "default_width": 640,
3038 "default_height": 320,
3039 "default_model": {
3040 "provider": "zed.dev",
3041 "model": "claude-3-7-sonnet-latest"
3042 },
3043 "editor_model": {
3044 "provider": "zed.dev",
3045 "model": "claude-3-7-sonnet-latest"
3046 }
3047}
3048```
3049
3050## Outline Panel
3051
3052- Description: Customize outline Panel
3053- Setting: `outline_panel`
3054- Default:
3055
3056```json
3057"outline_panel": {
3058 "button": true,
3059 "default_width": 300,
3060 "dock": "left",
3061 "file_icons": true,
3062 "folder_icons": true,
3063 "git_status": true,
3064 "indent_size": 20,
3065 "auto_reveal_entries": true,
3066 "auto_fold_dirs": true,
3067 "indent_guides": {
3068 "show": "always"
3069 },
3070 "scrollbar": {
3071 "show": null
3072 }
3073}
3074```
3075
3076## Calls
3077
3078- Description: Customize behavior when participating in a call
3079- Setting: `calls`
3080- Default:
3081
3082```json
3083"calls": {
3084 // Join calls with the microphone live by default
3085 "mute_on_join": false,
3086 // Share your project when you are the first to join a channel
3087 "share_on_join": false
3088},
3089```
3090
3091## Unnecessary Code Fade
3092
3093- Description: How much to fade out unused code.
3094- Setting: `unnecessary_code_fade`
3095- Default: `0.3`
3096
3097**Options**
3098
3099Float values between `0.0` and `0.9`, where:
3100
3101- `0.0` means no fading (unused code looks the same as used code)
3102- `0.9` means maximum fading (unused code is very faint but still visible)
3103
3104**Example**
3105
3106```json
3107{
3108 "unnecessary_code_fade": 0.5
3109}
3110```
3111
3112## UI Font Family
3113
3114- Description: The name of the font to use for text in the UI.
3115- Setting: `ui_font_family`
3116- Default: `Zed Plex Sans`
3117
3118**Options**
3119
3120The name of any font family installed on the system.
3121
3122## UI Font Features
3123
3124- Description: The OpenType features to enable for text in the UI.
3125- Setting: `ui_font_features`
3126- Default:
3127
3128```json
3129"ui_font_features": {
3130 "calt": false
3131}
3132```
3133
3134- Platform: macOS and Windows.
3135
3136**Options**
3137
3138Zed supports all OpenType features that can be enabled or disabled for a given UI font, as well as setting values for font features.
3139
3140For example, to disable font ligatures, add the following to your settings:
3141
3142```json
3143{
3144 "ui_font_features": {
3145 "calt": false
3146 }
3147}
3148```
3149
3150You can also set other OpenType features, like setting `cv01` to `7`:
3151
3152```json
3153{
3154 "ui_font_features": {
3155 "cv01": 7
3156 }
3157}
3158```
3159
3160## UI Font Fallbacks
3161
3162- Description: The font fallbacks to use for text in the UI.
3163- Setting: `ui_font_fallbacks`
3164- Default: `null`
3165- Platform: macOS and Windows.
3166
3167**Options**
3168
3169For example, to use `Nerd Font` as a fallback, add the following to your settings:
3170
3171```json
3172{
3173 "ui_font_fallbacks": ["Nerd Font"]
3174}
3175```
3176
3177## UI Font Size
3178
3179- Description: The default font size for text in the UI.
3180- Setting: `ui_font_size`
3181- Default: `16`
3182
3183**Options**
3184
3185`integer` values from `6` to `100` pixels (inclusive)
3186
3187## UI Font Weight
3188
3189- Description: The default font weight for text in the UI.
3190- Setting: `ui_font_weight`
3191- Default: `400`
3192
3193**Options**
3194
3195`integer` values between `100` and `900`
3196
3197## An example configuration:
3198
3199```json
3200// ~/.config/zed/settings.json
3201{
3202 "theme": "cave-light",
3203 "tab_size": 2,
3204 "preferred_line_length": 80,
3205 "soft_wrap": "none",
3206
3207 "buffer_font_size": 18,
3208 "buffer_font_family": "Zed Plex Mono",
3209
3210 "autosave": "on_focus_change",
3211 "format_on_save": "off",
3212 "vim_mode": false,
3213 "projects_online_by_default": true,
3214 "terminal": {
3215 "font_family": "FiraCode Nerd Font Mono",
3216 "blinking": "off"
3217 },
3218 "languages": {
3219 "C": {
3220 "format_on_save": "language_server",
3221 "preferred_line_length": 64,
3222 "soft_wrap": "preferred_line_length"
3223 }
3224 }
3225}
3226```