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::OpenLocalSettings} 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 Magnification
33
34- 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.
35- Setting: `active_pane_magnification`
36- Default: `1.0`
37
38**Options**
39
40`float` values
41
42## Autosave
43
44- Description: When to automatically save edited buffers.
45- Setting: `autosave`
46- Default: `off`
47
48**Options**
49
501. To disable autosave, set it to `off`:
51
52```json
53{
54 "autosave": "off"
55}
56```
57
582. To autosave when focus changes, use `on_focus_change`:
59
60```json
61{
62 "autosave": "on_focus_change"
63}
64```
65
663. To autosave when the active window changes, use `on_window_change`:
67
68```json
69{
70 "autosave": "on_window_change"
71}
72```
73
744. To autosave after an inactivity period, use `after_delay`:
75
76```json
77{
78 "autosave": {
79 "after_delay": {
80 "milliseconds": 1000
81 }
82 }
83}
84```
85
86## Auto Update
87
88- Description: Whether or not to automatically check for updates.
89- Setting: `auto_update`
90- Default: `true`
91
92**Options**
93
94`boolean` values
95
96## Base Keymap
97
98- Description: Base key bindings scheme. Base keymaps can be overridden with user keymaps.
99- Setting: `base_keymap`
100- Default: `VSCode`
101
102**Options**
103
1041. VSCode
105
106```json
107{
108 "base_keymap": "VSCode"
109}
110```
111
1122. Atom
113
114```json
115{
116 "base_keymap": "Atom"
117}
118```
119
1203. JetBrains
121
122```json
123{
124 "base_keymap": "JetBrains"
125}
126```
127
1284. None
129
130```json
131{
132 "base_keymap": "None"
133}
134```
135
1365. SublimeText
137
138```json
139{
140 "base_keymap": "SublimeText"
141}
142```
143
1446. TextMate
145
146```json
147{
148 "base_keymap": "TextMate"
149}
150```
151
152## Buffer Font Family
153
154- Description: The name of a font to use for rendering text in the editor.
155- Setting: `buffer_font_family`
156- Default: `Zed Plex Mono`
157
158**Options**
159
160The name of any font family installed on the user's system
161
162## Buffer Font Features
163
164- Description: The OpenType features to enable for text in the editor.
165- Setting: `buffer_font_features`
166- Default: `null`
167- Platform: macOS and Windows.
168
169**Options**
170
171Zed 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.
172
173For example, to disable font ligatures, add the following to your settings:
174
175```json
176{
177 "buffer_font_features": {
178 "calt": false
179 }
180}
181```
182
183You can also set other OpenType features, like setting `cv01` to `7`:
184
185```json
186{
187 "buffer_font_features": {
188 "cv01": 7
189 }
190}
191```
192
193## Buffer Font Fallbacks
194
195- Description: Set the buffer text's font fallbacks, this will be merged with the platform's default fallbacks.
196- Setting: `buffer_font_fallbacks`
197- Default: `null`
198- Platform: macOS and Windows.
199
200**Options**
201
202For example, to use `Nerd Font` as a fallback, add the following to your settings:
203
204```json
205{
206 "buffer_font_fallbacks": ["Nerd Font"]
207}
208```
209
210## Buffer Font Size
211
212- Description: The default font size for text in the editor.
213- Setting: `buffer_font_size`
214- Default: `15`
215
216**Options**
217
218`integer` values from `6` to `100` pixels (inclusive)
219
220## Buffer Font Weight
221
222- Description: The default font weight for text in the editor.
223- Setting: `buffer_font_weight`
224- Default: `400`
225
226**Options**
227
228`integer` values between `100` and `900`
229
230## Buffer Line Height
231
232- Description: The default line height for text in the editor.
233- Setting: `buffer_line_height`
234- Default: `"comfortable"`
235
236**Options**
237
238`"standard"`, `"comfortable"` or `{"custom": float}` (`1` is very compact, `2` very loose)
239
240## Confirm Quit
241
242- Description: Whether or not to prompt the user to confirm before closing the application.
243- Setting: `confirm_quit`
244- Default: `false`
245
246**Options**
247
248`boolean` values
249
250## Centered Layout
251
252- Description: Configuration for the centered layout mode.
253- Setting: `centered_layout`
254- Default:
255
256```json
257"centered_layout": {
258 "left_padding": 0.2,
259 "right_padding": 0.2,
260}
261```
262
263**Options**
264
265The `left_padding` and `right_padding` options define the relative width of the
266left 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`.
267
268## Direnv Integration
269
270- Description: Settings for [direnv](https://direnv.net/) integration. Requires `direnv` to be installed.
271 `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.
272 It also allows for those environment variables to be used in tasks.
273- Setting: `load_direnv`
274- Default:
275
276```json
277"load_direnv": "direct"
278```
279
280**Options**
281There are two options to choose from:
282
2831. `shell_hook`: Use the shell hook to load direnv. This relies on direnv to activate upon entering the directory. Supports POSIX shells and fish.
2842. `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.
285
286## Inline Completions
287
288- Description: Settings for inline completions.
289- Setting: `inline_completions`
290- Default:
291
292```json
293"inline_completions": {
294 "disabled_globs": [
295 ".env"
296 ]
297}
298```
299
300**Options**
301
302### Disabled Globs
303
304- Description: A list of globs representing files that inline completions should be disabled for.
305- Setting: `disabled_globs`
306- Default: `[".env"]`
307
308**Options**
309
310List of `string` values
311
312## Current Line Highlight
313
314- Description: How to highlight the current line in the editor.
315- Setting: `current_line_highlight`
316- Default: `all`
317
318**Options**
319
3201. Don't highlight the current line:
321
322```json
323"current_line_highlight": "none"
324```
325
3262. Highlight the gutter area:
327
328```json
329"current_line_highlight": "gutter"
330```
331
3323. Highlight the editor area:
333
334```json
335"current_line_highlight": "line"
336```
337
3384. Highlight the full line:
339
340```json
341"current_line_highlight": "all"
342```
343
344## Cursor Blink
345
346- Description: Whether or not the cursor blinks.
347- Setting: `cursor_blink`
348- Default: `true`
349
350**Options**
351
352`boolean` values
353
354## Cursor Shape
355
356- Description: Cursor shape for the default editor.
357- Setting: `cursor_shape`
358- Default: `bar`
359
360**Options**
361
3621. A vertical bar:
363
364```json
365"cursor_shape": "bar"
366```
367
3682. A block that surrounds the following character:
369
370```json
371"cursor_shape": "block"
372```
373
3743. An underscore that runs along the following character:
375
376```json
377"cursor_shape": "underscore"
378```
379
3804. An box drawn around the following character:
381
382```json
383"cursor_shape": "hollow"
384```
385
386**Options**
387
3881. Position the dock attached to the bottom of the workspace: `bottom`
3892. Position the dock to the right of the workspace like a side panel: `right`
3903. Position the dock full screen over the entire workspace: `expanded`
391
392## Editor Scrollbar
393
394- Description: Whether or not to show the editor scrollbar and various elements in it.
395- Setting: `scrollbar`
396- Default:
397
398```json
399"scrollbar": {
400 "show": "auto",
401 "cursors": true,
402 "git_diff": true,
403 "search_results": true,
404 "selected_symbol": true,
405 "diagnostics": true
406},
407```
408
409### Show Mode
410
411- Description: When to show the editor scrollbar.
412- Setting: `show`
413- Default: `auto`
414
415**Options**
416
4171. Show the scrollbar if there's important information or follow the system's configured behavior:
418
419```json
420"scrollbar": {
421 "show": "auto"
422}
423```
424
4252. Match the system's configured behavior:
426
427```json
428"scrollbar": {
429 "show": "system"
430}
431```
432
4333. Always show the scrollbar:
434
435```json
436"scrollbar": {
437 "show": "always"
438}
439```
440
4414. Never show the scrollbar:
442
443```json
444"scrollbar": {
445 "show": "never"
446}
447```
448
449### Cursor Indicators
450
451- Description: Whether to show cursor positions in the scrollbar.
452- Setting: `cursors`
453- Default: `true`
454
455**Options**
456
457`boolean` values
458
459### Git Diff Indicators
460
461- Description: Whether to show git diff indicators in the scrollbar.
462- Setting: `git_diff`
463- Default: `true`
464
465**Options**
466
467`boolean` values
468
469### Search Results Indicators
470
471- Description: Whether to show buffer search results in the scrollbar.
472- Setting: `search_results`
473- Default: `true`
474
475**Options**
476
477`boolean` values
478
479### Selected Symbols Indicators
480
481- Description: Whether to show selected symbol occurrences in the scrollbar.
482- Setting: `selected_symbol`
483- Default: `true`
484
485**Options**
486
487`boolean` values
488
489### Diagnostics
490
491- Description: Whether to show diagnostic indicators in the scrollbar.
492- Setting: `diagnostics`
493- Default: `true`
494
495**Options**
496
497`boolean` values
498
499## Editor Tab Bar
500
501- Description: Settings related to the editor's tab bar.
502- Settings: `tab_bar`
503- Default:
504
505```json
506"tab_bar": {
507 "show": true,
508 "show_nav_history_buttons": true
509}
510```
511
512### Show
513
514- Description: Whether or not to show the tab bar in the editor.
515- Setting: `show`
516- Default: `true`
517
518**Options**
519
520`boolean` values
521
522### Navigation History Buttons
523
524- Description: Whether or not to show the navigation history buttons.
525- Setting: `show_nav_history_buttons`
526- Default: `true`
527
528**Options**
529
530`boolean` values
531
532## Editor Tabs
533
534- Description: Configuration for the editor tabs.
535- Setting: `tabs`
536- Default:
537
538```json
539"tabs": {
540 "close_position": "right",
541 "file_icons": false,
542 "git_status": false
543},
544```
545
546### Close Position
547
548- Description: Where to display close button within a tab.
549- Setting: `close_position`
550- Default: `right`
551
552**Options**
553
5541. Display the close button on the right:
555
556```json
557{
558 "close_position": "right"
559}
560```
561
5622. Display the close button on the left:
563
564```json
565{
566 "close_position": "left"
567}
568```
569
570### File Icons
571
572- Description: Whether to show the file icon for a tab.
573- Setting: `file_icons`
574- Default: `false`
575
576### Git Status
577
578- Description: Whether or not to show Git file status in tab.
579- Setting: `git_status`
580- Default: `false`
581
582## Editor Toolbar
583
584- Description: Whether or not to show various elements in the editor toolbar.
585- Setting: `toolbar`
586- Default:
587
588```json
589"toolbar": {
590 "breadcrumbs": true,
591 "quick_actions": true
592},
593```
594
595**Options**
596
597Each option controls displaying of a particular toolbar element. If all elements are hidden, the editor toolbar is not displayed.
598
599## Enable Language Server
600
601- Description: Whether or not to use language servers to provide code intelligence.
602- Setting: `enable_language_server`
603- Default: `true`
604
605**Options**
606
607`boolean` values
608
609## Ensure Final Newline On Save
610
611- Description: Whether or not to ensure there's a single newline at the end of a buffer when saving it.
612- Setting: `ensure_final_newline_on_save`
613- Default: `true`
614
615**Options**
616
617`boolean` values
618
619## LSP
620
621- Description: Configuration for language servers.
622- Setting: `lsp`
623- Default: `null`
624
625**Options**
626
627The following settings can be overridden for specific language servers:
628
629- `initialization_options`
630- `settings`
631
632To override configuration for a language server, add an entry for that language server's name to the `lsp` value.
633
634Some 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.
635
636For example to pass the `check` option to `rust-analyzer`, use the following configuration:
637
638```json
639"lsp": {
640 "rust-analyzer": {
641 "initialization_options": {
642 "check": {
643 "command": "clippy" // rust-analyzer.check.command (default: "check")
644 }
645 }
646 }
647}
648```
649
650While other options may be changed at a runtime and should be placed under `settings`:
651
652```json
653"lsp": {
654 "yaml-language-server": {
655 "settings": {
656 "yaml": {
657 "keyOrdering": true // Enforces alphabetical ordering of keys in maps
658 }
659 }
660 }
661}
662```
663
664## Format On Save
665
666- Description: Whether or not to perform a buffer format before saving.
667- Setting: `format_on_save`
668- Default: `on`
669
670**Options**
671
6721. `on`, enables format on save obeying `formatter` setting:
673
674```json
675{
676 "format_on_save": "on"
677}
678```
679
6802. `off`, disables format on save:
681
682```json
683{
684 "format_on_save": "off"
685}
686```
687
688## Formatter
689
690- Description: How to perform a buffer format.
691- Setting: `formatter`
692- Default: `auto`
693
694**Options**
695
6961. To use the current language server, use `"language_server"`:
697
698```json
699{
700 "formatter": "language_server"
701}
702```
703
7042. 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):
705
706```json
707{
708 "formatter": {
709 "external": {
710 "command": "sed",
711 "arguments": ["-e", "s/ *$//"]
712 }
713 }
714}
715```
716
7173. Or to use code actions provided by the connected language servers, use `"code_actions"`:
718
719```json
720{
721 "formatter": {
722 "code_actions": {
723 // Use ESLint's --fix:
724 "source.fixAll.eslint": true,
725 // Organize imports on save:
726 "source.organizeImports": true
727 }
728 }
729}
730```
731
7324. Or to use multiple formatters consecutively, use an array of formatters:
733
734```json
735{
736 "formatter": [
737 {"language_server": {"name": "rust-analyzer"}},
738 {"external": {
739 "command": "sed",
740 "arguments": ["-e", "s/ *$//"]
741 }
742 ]
743}
744```
745
746Here `rust-analyzer` will be used first to format the code, followed by a call of sed.
747If any of the formatters fails, the subsequent ones will still be executed.
748
749## Code Actions On Format
750
751- Description: The code actions to perform with the primary language server when formatting the buffer.
752- Setting: `code_actions_on_format`
753- Default: `{}`, except for Go it's `{ "source.organizeImports": true }`
754
755**Examples**
756
757<!--
758TBD: Add Python Ruff source.organizeImports example
759-->
760
7611. Organize imports on format in TypeScript and TSX buffers:
762
763```json
764{
765 "languages": {
766 "TypeScript": {
767 "code_actions_on_format": {
768 "source.organizeImports": true
769 }
770 },
771 "TSX": {
772 "code_actions_on_format": {
773 "source.organizeImports": true
774 }
775 }
776 }
777}
778```
779
7802. Run ESLint `fixAll` code action when formatting:
781
782```json
783{
784 "languages": {
785 "JavaScript": {
786 "code_actions_on_format": {
787 "source.fixAll.eslint": true
788 }
789 }
790 }
791}
792```
793
7943. Run only a single ESLint rule when using `fixAll`:
795
796```json
797{
798 "languages": {
799 "JavaScript": {
800 "code_actions_on_format": {
801 "source.fixAll.eslint": true
802 }
803 }
804 },
805 "lsp": {
806 "eslint": {
807 "settings": {
808 "codeActionOnSave": {
809 "rules": ["import/order"]
810 }
811 }
812 }
813 }
814}
815```
816
817## Auto close
818
819- Description: Whether to automatically add matching closing characters when typing opening parenthesis, bracket, brace, single or double quote characters.
820- Setting: `use_autoclose`
821- Default: `true`
822
823**Options**
824
825`boolean` values
826
827## Always Treat Brackets As Autoclosed
828
829- Description: Controls how the editor handles the autoclosed characters.
830- Setting: `always_treat_brackets_as_autoclosed`
831- Default: `false`
832
833**Options**
834
835`boolean` values
836
837**Example**
838
839If the setting is set to `true`:
840
8411. Enter in the editor: `)))`
8422. Move the cursor to the start: `^)))`
8433. Enter again: `)))`
844
845The result is still `)))` and not `))))))`, which is what it would be by default.
846
847## File Types
848
849- Setting: `file_types`
850- Description: Configure how Zed selects a language for a file based on its filename or extension. Supports glob entries.
851- Default: `{}`
852
853**Examples**
854
855To interpret all `.c` files as C++, files called `MyLockFile` as TOML and files starting with `Dockerfile` as Dockerfile:
856
857```json
858{
859 "file_types": {
860 "C++": ["c"],
861 "TOML": ["MyLockFile"],
862 "Dockerfile": ["Dockerfile*"]
863 }
864}
865```
866
867## Git
868
869- Description: Configuration for git-related features.
870- Setting: `git`
871- Default:
872
873```json
874{
875 "git": {
876 "git_gutter": "tracked_files",
877 "inline_blame": {
878 "enabled": true
879 }
880 }
881}
882```
883
884### Git Gutter
885
886- Description: Whether or not to show the git gutter.
887- Setting: `git_gutter`
888- Default: `tracked_files`
889
890**Options**
891
8921. Show git gutter in tracked files
893
894```json
895{
896 "git": {
897 "git_gutter": "tracked_files"
898 }
899}
900```
901
9022. Hide git gutter
903
904```json
905{
906 "git": {
907 "git_gutter": "hide"
908 }
909}
910```
911
912### Inline Git Blame
913
914- Description: Whether or not to show git blame information inline, on the currently focused line.
915- Setting: `inline_blame`
916- Default:
917
918```json
919{
920 "git": {
921 "inline_blame": {
922 "enabled": true
923 }
924 }
925}
926```
927
928**Options**
929
9301. Disable inline git blame:
931
932```json
933{
934 "git": {
935 "inline_blame": {
936 "enabled": false
937 }
938 }
939}
940```
941
9422. Only show inline git blame after a delay (that starts after cursor stops moving):
943
944```json
945{
946 "git": {
947 "inline_blame": {
948 "enabled": true,
949 "delay_ms": 500
950 }
951 }
952}
953```
954
955## Indent Guides
956
957- Description: Configuration related to indent guides. Indent guides can be configured separately for each language.
958- Setting: `indent_guides`
959- Default:
960
961```json
962{
963 "indent_guides": {
964 "enabled": true,
965 "line_width": 1,
966 "active_line_width": 1,
967 "coloring": "fixed",
968 "background_coloring": "disabled"
969 }
970}
971```
972
973**Options**
974
9751. Disable indent guides
976
977```json
978{
979 "indent_guides": {
980 "enabled": false
981 }
982}
983```
984
9852. Enable indent guides for a specific language.
986
987```json
988{
989 "languages": {
990 "Python": {
991 "indent_guides": {
992 "enabled": true
993 }
994 }
995 }
996}
997```
998
9993. Enable indent aware coloring ("rainbow indentation").
1000 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.
1001
1002```json
1003{
1004 "indent_guides": {
1005 "enabled": true,
1006 "coloring": "indent_aware"
1007 }
1008}
1009```
1010
10114. Enable indent aware background coloring ("rainbow indentation").
1012 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.
1013
1014```json
1015{
1016 "indent_guides": {
1017 "enabled": true,
1018 "coloring": "indent_aware",
1019 "background_coloring": "indent_aware"
1020 }
1021}
1022```
1023
1024## Hard Tabs
1025
1026- Description: Whether to indent lines using tab characters or multiple spaces.
1027- Setting: `hard_tabs`
1028- Default: `false`
1029
1030**Options**
1031
1032`boolean` values
1033
1034## Hover Popover Enabled
1035
1036- Description: Whether or not to show the informational hover box when moving the mouse over symbols in the editor.
1037- Setting: `hover_popover_enabled`
1038- Default: `true`
1039
1040**Options**
1041
1042`boolean` values
1043
1044## Inlay hints
1045
1046- Description: Configuration for displaying extra text with hints in the editor.
1047- Setting: `inlay_hints`
1048- Default:
1049
1050```json
1051"inlay_hints": {
1052 "enabled": false,
1053 "show_type_hints": true,
1054 "show_parameter_hints": true,
1055 "show_other_hints": true,
1056 "show_background": false,
1057 "edit_debounce_ms": 700,
1058 "scroll_debounce_ms": 50
1059}
1060```
1061
1062**Options**
1063
1064Inlay hints querying consists of two parts: editor (client) and LSP server.
1065With 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.
1066At 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.
1067
1068The following languages have inlay hints preconfigured by Zed:
1069
1070- [Go](https://docs.zed.dev/languages/go)
1071- [Rust](https://docs.zed.dev/languages/rust)
1072- [Svelte](https://docs.zed.dev/languages/svelte)
1073- [Typescript](https://docs.zed.dev/languages/typescript)
1074
1075Use the `lsp` section for the server configuration. Examples are provided in the corresponding language documentation.
1076
1077Hints are not instantly queried in Zed, two kinds of debounces are used, either may be set to 0 to be disabled.
1078Settings-related hint updates are not debounced.
1079
1080## Journal
1081
1082- Description: Configuration for the journal.
1083- Setting: `journal`
1084- Default:
1085
1086```json
1087"journal": {
1088 "path": "~",
1089 "hour_format": "hour12"
1090}
1091```
1092
1093### Path
1094
1095- Description: The path of the directory where journal entries are stored.
1096- Setting: `path`
1097- Default: `~`
1098
1099**Options**
1100
1101`string` values
1102
1103### Hour Format
1104
1105- Description: The format to use for displaying hours in the journal.
1106- Setting: `hour_format`
1107- Default: `hour12`
1108
1109**Options**
1110
11111. 12-hour format:
1112
1113```json
1114{
1115 "hour_format": "hour12"
1116}
1117```
1118
11192. 24-hour format:
1120
1121```json
1122{
1123 "hour_format": "hour24"
1124}
1125```
1126
1127## Languages
1128
1129- Description: Configuration for specific languages.
1130- Setting: `languages`
1131- Default: `null`
1132
1133**Options**
1134
1135To override settings for a language, add an entry for that languages name to the `languages` value. Example:
1136
1137```json
1138"languages": {
1139 "C": {
1140 "format_on_save": "off",
1141 "preferred_line_length": 64,
1142 "soft_wrap": "preferred_line_length"
1143 },
1144 "JSON": {
1145 "tab_size": 4
1146 }
1147}
1148```
1149
1150The following settings can be overridden for each specific language:
1151
1152- `enable_language_server`
1153- `ensure_final_newline_on_save`
1154- `format_on_save`
1155- `formatter`
1156- `hard_tabs`
1157- `preferred_line_length`
1158- `remove_trailing_whitespace_on_save`
1159- `show_inline_completions`
1160- `show_whitespaces`
1161- `soft_wrap`
1162- `tab_size`
1163- `use_autoclose`
1164- `always_treat_brackets_as_autoclosed`
1165
1166These values take in the same options as the root-level settings with the same name.
1167
1168## Network Proxy
1169
1170- Description: Configure a network proxy for Zed.
1171- Setting: `proxy`
1172- Default: `null`
1173
1174**Options**
1175
1176The proxy setting must contain a URL to the proxy.
1177
1178The following URI schemes are supported:
1179
1180- `http`
1181- `https`
1182- `socks4` - SOCKS4 proxy with local DNS
1183- `socks4a` - SOCKS4 proxy with remote DNS
1184- `socks5` - SOCKS5 proxy with local DNS
1185- `socks5h` - SOCKS5 proxy with remote DNS
1186
1187`http` will be used when no scheme is specified.
1188
1189By 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`.
1190
1191For example, to set an `http` proxy, add the following to your settings:
1192
1193```json
1194{
1195 "proxy": "http://127.0.0.1:10809"
1196}
1197```
1198
1199Or to set a `socks5` proxy:
1200
1201```json
1202{
1203 "proxy": "socks5h://localhost:10808"
1204}
1205```
1206
1207## Preview tabs
1208
1209- Description:
1210 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. \
1211 There are several ways to convert a preview tab into a regular tab:
1212
1213 - Double-clicking on the file
1214 - Double-clicking on the tab header
1215 - Using the `project_panel::OpenPermanent` action
1216 - Editing the file
1217 - Dragging the file to a different pane
1218
1219- Setting: `preview_tabs`
1220- Default:
1221
1222```json
1223"preview_tabs": {
1224 "enabled": true,
1225 "enable_preview_from_file_finder": false,
1226 "enable_preview_from_code_navigation": false,
1227}
1228```
1229
1230### Enable preview from file finder
1231
1232- Description: Determines whether to open files in preview mode when selected from the file finder.
1233- Setting: `enable_preview_from_file_finder`
1234- Default: `false`
1235
1236**Options**
1237
1238`boolean` values
1239
1240### Enable preview from code navigation
1241
1242- Description: Determines whether a preview tab gets replaced when code navigation is used to navigate away from the tab.
1243- Setting: `enable_preview_from_code_navigation`
1244- Default: `false`
1245
1246**Options**
1247
1248`boolean` values
1249
1250## Preferred Line Length
1251
1252- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
1253- Setting: `preferred_line_length`
1254- Default: `80`
1255
1256**Options**
1257
1258`integer` values
1259
1260## Projects Online By Default
1261
1262- Description: Whether or not to show the online projects view by default.
1263- Setting: `projects_online_by_default`
1264- Default: `true`
1265
1266**Options**
1267
1268`boolean` values
1269
1270## Remove Trailing Whitespace On Save
1271
1272- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
1273- Setting: `remove_trailing_whitespace_on_save`
1274- Default: `true`
1275
1276**Options**
1277
1278`boolean` values
1279
1280## Search
1281
1282- Description: Search options to enable by default when opening new project and buffer searches.
1283- Setting: `search`
1284- Default:
1285
1286```json
1287"search": {
1288 "whole_word": false,
1289 "case_sensitive": false,
1290 "include_ignored": false,
1291 "regex": false
1292},
1293```
1294
1295## Show Call Status Icon
1296
1297- Description: Whether or not to show the call status icon in the status bar.
1298- Setting: `show_call_status_icon`
1299- Default: `true`
1300
1301**Options**
1302
1303`boolean` values
1304
1305## Show Completions On Input
1306
1307- Description: Whether or not to show completions as you type.
1308- Setting: `show_completions_on_input`
1309- Default: `true`
1310
1311**Options**
1312
1313`boolean` values
1314
1315## Show Completion Documentation
1316
1317- Description: Whether to display inline and alongside documentation for items in the completions menu.
1318- Setting: `show_completion_documentation`
1319- Default: `true`
1320
1321**Options**
1322
1323`boolean` values
1324
1325## Completion Documentation Debounce Delay
1326
1327- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
1328- Setting: `completion_documentation_secondary_query_debounce`
1329- Default: `300` ms
1330
1331**Options**
1332
1333`integer` values
1334
1335## Show Inline Completions
1336
1337- Description: Whether to show inline completions as you type or manually by triggering `editor::ShowInlineCompletion`.
1338- Setting: `show_inline_completions`
1339- Default: `true`
1340
1341**Options**
1342
1343`boolean` values
1344
1345## Show Whitespaces
1346
1347- Description: Whether or not to show render whitespace characters in the editor.
1348- Setting: `show_whitespaces`
1349- Default: `selection`
1350
1351**Options**
1352
13531. `all`
13542. `selection`
13553. `none`
13564. `boundary`
1357
1358## Soft Wrap
1359
1360- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
1361- Setting: `soft_wrap`
1362- Default: `none`
1363
1364**Options**
1365
13661. `none` to avoid wrapping generally, unless the line is too long
13672. `prefer_line` (deprecated, same as `none`)
13683. `editor_width` to wrap lines that overflow the editor width
13694. `preferred_line_length` to wrap lines that overflow `preferred_line_length` config value
1370
1371## Wrap Guides (Vertical Rulers)
1372
1373- Description: Where to display vertical rulers as wrap-guides. Disable by setting `show_wrap_guides` to `false`.
1374- Setting: `wrap_guides`
1375- Default: []
1376
1377**Options**
1378
1379List of `integer` column numbers
1380
1381## Tab Size
1382
1383- Description: The number of spaces to use for each tab character.
1384- Setting: `tab_size`
1385- Default: `4`
1386
1387**Options**
1388
1389`integer` values
1390
1391## Telemetry
1392
1393- Description: Control what info is collected by Zed.
1394- Setting: `telemetry`
1395- Default:
1396
1397```json
1398"telemetry": {
1399 "diagnostics": true,
1400 "metrics": true
1401},
1402```
1403
1404**Options**
1405
1406### Diagnostics
1407
1408- Description: Setting for sending debug-related data, such as crash reports.
1409- Setting: `diagnostics`
1410- Default: `true`
1411
1412**Options**
1413
1414`boolean` values
1415
1416### Metrics
1417
1418- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
1419- Setting: `metrics`
1420- Default: `true`
1421
1422**Options**
1423
1424`boolean` values
1425
1426## Terminal
1427
1428- Description: Configuration for the terminal.
1429- Setting: `terminal`
1430- Default:
1431
1432```json
1433{
1434 "terminal": {
1435 "alternate_scroll": "off",
1436 "blinking": "terminal_controlled",
1437 "copy_on_select": false,
1438 "dock": "bottom",
1439 "detect_venv": {
1440 "on": {
1441 "directories": [".env", "env", ".venv", "venv"],
1442 "activate_script": "default"
1443 }
1444 }
1445 "env": {},
1446 "font_family": null,
1447 "font_features": null,
1448 "font_size": null,
1449 "line_height": "comfortable",
1450 "option_as_meta": true,
1451 "button": false,
1452 "shell": {},
1453 "toolbar": {
1454 "title": true
1455 },
1456 "working_directory": "current_project_directory"
1457 }
1458}
1459```
1460
1461### Terminal: Dock
1462
1463- Description: Control the position of the dock
1464- Setting: `dock`
1465- Default: `bottom`
1466
1467**Options**
1468
1469`"bottom"`, `"left"` or `"right"`
1470
1471### Terminal: Alternate Scroll
1472
1473- 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.
1474- Setting: `alternate_scroll`
1475- Default: `off`
1476
1477**Options**
1478
14791. Default alternate scroll mode to on
1480
1481```json
1482{
1483 "terminal": {
1484 "alternate_scroll": "on"
1485 }
1486}
1487```
1488
14892. Default alternate scroll mode to off
1490
1491```json
1492{
1493 "terminal": {
1494 "alternate_scroll": "off"
1495 }
1496}
1497```
1498
1499### Terminal: Blinking
1500
1501- Description: Set the cursor blinking behavior in the terminal
1502- Setting: `blinking`
1503- Default: `terminal_controlled`
1504
1505**Options**
1506
15071. Never blink the cursor, ignore the terminal mode
1508
1509```json
1510{
1511 "terminal": {
1512 "blinking": "off"
1513 }
1514}
1515```
1516
15172. Default the cursor blink to off, but allow the terminal to turn blinking on
1518
1519```json
1520{
1521 "terminal": {
1522 "blinking": "terminal_controlled"
1523 }
1524}
1525```
1526
15273. Always blink the cursor, ignore the terminal mode
1528
1529```json
1530{
1531 "terminal": {
1532 "blinking": "on"
1533 }
1534}
1535```
1536
1537### Terminal: Copy On Select
1538
1539- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
1540- Setting: `copy_on_select`
1541- Default: `false`
1542
1543**Options**
1544
1545`boolean` values
1546
1547**Example**
1548
1549```json
1550{
1551 "terminal": {
1552 "copy_on_select": true
1553 }
1554}
1555```
1556
1557### Terminal: Env
1558
1559- 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
1560- Setting: `env`
1561- Default: `{}`
1562
1563**Example**
1564
1565```json
1566{
1567 "terminal": {
1568 "env": {
1569 "ZED": "1",
1570 "KEY": "value1:value2"
1571 }
1572 }
1573}
1574```
1575
1576### Terminal: Font Size
1577
1578- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
1579- Setting: `font_size`
1580- Default: `null`
1581
1582**Options**
1583
1584`integer` values
1585
1586```json
1587{
1588 "terminal": {
1589 "font_size": 15
1590 }
1591}
1592```
1593
1594### Terminal: Font Family
1595
1596- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
1597- Setting: `font_family`
1598- Default: `null`
1599
1600**Options**
1601
1602The name of any font family installed on the user's system
1603
1604```json
1605{
1606 "terminal": {
1607 "font_family": "Berkeley Mono"
1608 }
1609}
1610```
1611
1612### Terminal: Font Features
1613
1614- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
1615- Setting: `font_features`
1616- Default: `null`
1617- Platform: macOS and Windows.
1618
1619**Options**
1620
1621See Buffer Font Features
1622
1623```json
1624{
1625 "terminal": {
1626 "font_features": {
1627 "calt": false
1628 // See Buffer Font Features for more features
1629 }
1630 }
1631}
1632```
1633
1634### Terminal: Line Height
1635
1636- Description: Set the terminal's line height.
1637- Setting: `line_height`
1638- Default: `comfortable`
1639
1640**Options**
1641
16421. Use a line height that's `comfortable` for reading, 1.618. (default)
1643
1644```json
1645{
1646 "terminal": {
1647 "line_height": "comfortable"
1648 }
1649}
1650```
1651
16522. Use a `standard` line height, 1.3. This option is useful for TUIs, particularly if they use box characters
1653
1654```json
1655{
1656 "terminal": {
1657 "line_height": "standard"
1658 }
1659}
1660```
1661
16623. Use a custom line height.
1663
1664```json
1665{
1666 "terminal": {
1667 "line_height": {
1668 "custom": 2
1669 }
1670 }
1671}
1672```
1673
1674### Terminal: Option As Meta
1675
1676- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
1677- Setting: `option_as_meta`
1678- Default: `true`
1679
1680**Options**
1681
1682`boolean` values
1683
1684```json
1685{
1686 "terminal": {
1687 "option_as_meta": true
1688 }
1689}
1690```
1691
1692### Terminal: Shell
1693
1694- Description: What shell to use when launching the terminal.
1695- Setting: `shell`
1696- Default: `system`
1697
1698**Options**
1699
17001. Use the system's default terminal configuration (usually the `/etc/passwd` file).
1701
1702```json
1703{
1704 "terminal": {
1705 "shell": "system"
1706 }
1707}
1708```
1709
17102. A program to launch:
1711
1712```json
1713{
1714 "terminal": {
1715 "shell": {
1716 "program": "sh"
1717 }
1718 }
1719}
1720```
1721
17223. A program with arguments:
1723
1724```json
1725{
1726 "terminal": {
1727 "shell": {
1728 "with_arguments": {
1729 "program": "/bin/bash",
1730 "args": ["--login"]
1731 }
1732 }
1733 }
1734}
1735```
1736
1737## Terminal: Detect Virtual Environments {#terminal-detect_venv}
1738
1739- 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.
1740- Setting: `detect_venv`
1741- Default:
1742
1743```json
1744{
1745 "terminal":
1746 "detect_venv": {
1747 "on": {
1748 // Default directories to search for virtual environments, relative
1749 // to the current working directory. We recommend overriding this
1750 // in your project's settings, rather than globally.
1751 "directories": [".venv", "venv"],
1752 // Can also be `csh`, `fish`, and `nushell`
1753 "activate_script": "default"
1754 }
1755 }
1756 }
1757}
1758```
1759
1760Disable with:
1761
1762```json
1763{
1764 "terminal":
1765 "detect_venv": "off"
1766 }
1767}
1768```
1769
1770## Terminal: Toolbar
1771
1772- Description: Whether or not to show various elements in the terminal toolbar. It only affects terminals placed in the editor pane.
1773- Setting: `toolbar`
1774- Default:
1775
1776```json
1777{
1778 "terminal": {
1779 "toolbar": {
1780 "title": true
1781 }
1782 }
1783}
1784```
1785
1786**Options**
1787
1788At the moment, only the `title` option is available, it controls displaying of the terminal title that can be changed via `PROMPT_COMMAND`. If the title is hidden, the terminal toolbar is not displayed.
1789
1790### Terminal: Button
1791
1792- Description: Control to show or hide the terminal button in the status bar
1793- Setting: `button`
1794- Default: `true`
1795
1796**Options**
1797
1798`boolean` values
1799
1800```json
1801{
1802 "terminal": {
1803 "button": false
1804 }
1805}
1806```
1807
1808### Terminal: Working Directory
1809
1810- Description: What working directory to use when launching the terminal.
1811- Setting: `working_directory`
1812- Default: `"current_project_directory"`
1813
1814**Options**
1815
18161. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
1817
1818```json
1819{
1820 "terminal": {
1821 "working_directory": "current_project_directory"
1822 }
1823}
1824```
1825
18262. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
1827
1828```json
1829{
1830 "terminal": {
1831 "working_directory": "first_project_directory"
1832 }
1833}
1834```
1835
18363. Always use this platform's home directory (if we can find it)
1837
1838```json
1839{
1840 "terminal": {
1841 "working_directory": "always_home"
1842 }
1843}
1844```
1845
18464. 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.
1847
1848```json
1849{
1850 "terminal": {
1851 "working_directory": {
1852 "always": {
1853 "directory": "~/zed/projects/"
1854 }
1855 }
1856 }
1857}
1858```
1859
1860## Theme
1861
1862- 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.
1863- Setting: `theme`
1864- Default: `One Dark`
1865
1866### Theme Object
1867
1868- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
1869- Setting: `theme`
1870- Default:
1871
1872```json
1873"theme": {
1874 "mode": "system",
1875 "dark": "One Dark",
1876 "light": "One Light"
1877},
1878```
1879
1880### Mode
1881
1882- Description: Specify theme mode.
1883- Setting: `mode`
1884- Default: `system`
1885
1886**Options**
1887
18881. Set the theme to dark mode
1889
1890```json
1891{
1892 "mode": "dark"
1893}
1894```
1895
18962. Set the theme to light mode
1897
1898```json
1899{
1900 "mode": "light"
1901}
1902```
1903
19043. Set the theme to system mode
1905
1906```json
1907{
1908 "mode": "system"
1909}
1910```
1911
1912### Dark
1913
1914- Description: The name of the dark Zed theme to use for the UI.
1915- Setting: `dark`
1916- Default: `One Dark`
1917
1918**Options**
1919
1920Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1921
1922### Light
1923
1924- Description: The name of the light Zed theme to use for the UI.
1925- Setting: `light`
1926- Default: `One Light`
1927
1928**Options**
1929
1930Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1931
1932## Vim
1933
1934- Description: Whether or not to enable vim mode (work in progress).
1935- Setting: `vim_mode`
1936- Default: `false`
1937
1938## Project Panel
1939
1940- Description: Customize project panel
1941- Setting: `project_panel`
1942- Default:
1943
1944```json
1945{
1946 "project_panel": {
1947 "button": true,
1948 "default_width": 240,
1949 "dock": "left",
1950 "file_icons": true,
1951 "folder_icons": true,
1952 "git_status": true,
1953 "indent_size": 20,
1954 "auto_reveal_entries": true,
1955 "auto_fold_dirs": true,
1956 "scrollbar": {
1957 "show": null
1958 }
1959 }
1960}
1961```
1962
1963### Dock
1964
1965- Description: Control the position of the dock
1966- Setting: `dock`
1967- Default: `left`
1968
1969**Options**
1970
19711. Default dock position to left
1972
1973```json
1974{
1975 "dock": "left"
1976}
1977```
1978
19792. Default dock position to right
1980
1981```json
1982{
1983 "dock": "right"
1984}
1985```
1986
1987### Git Status
1988
1989- Description: Indicates newly created and updated files
1990- Setting: `git_status`
1991- Default: `true`
1992
1993**Options**
1994
19951. Default enable git status
1996
1997```json
1998{
1999 "git_status": true
2000}
2001```
2002
20032. Default disable git status
2004
2005```json
2006{
2007 "git_status": false
2008}
2009```
2010
2011### Default Width
2012
2013- Description: Customize default width taken by project panel
2014- Setting: `default_width`
2015- Default: N/A width in pixels (eg: 420)
2016
2017**Options**
2018
2019`boolean` values
2020
2021### Auto Reveal Entries
2022
2023- Description: Whether to reveal it in the project panel automatically, when a corresponding project entry becomes active. Gitignored entries are never auto revealed.
2024- Setting: `auto_reveal_entries`
2025- Default: `true`
2026
2027**Options**
2028
20291. Enable auto reveal entries
2030
2031```json
2032{
2033 "auto_reveal_entries": true
2034}
2035```
2036
20372. Disable auto reveal entries
2038
2039```json
2040{
2041 "auto_reveal_entries": false
2042}
2043```
2044
2045### Auto Fold Dirs
2046
2047- Description: Whether to fold directories automatically when directory has only one directory inside.
2048- Setting: `auto_fold_dirs`
2049- Default: `true`
2050
2051**Options**
2052
20531. Enable auto fold dirs
2054
2055```json
2056{
2057 "auto_fold_dirs": true
2058}
2059```
2060
20612. Disable auto fold dirs
2062
2063```json
2064{
2065 "auto_fold_dirs": false
2066}
2067```
2068
2069### Indent Size
2070
2071- Description: Amount of indentation (in pixels) for nested items.
2072- Setting: `indent_size`
2073- Default: `20`
2074
2075### Scrollbar
2076
2077- Description: Scrollbar related settings. Possible values: null, "auto", "system", "always", "never". Inherits editor settings when absent, see its description for more details.
2078- Setting: `scrollbar`
2079- Default:
2080
2081```json
2082"scrollbar": {
2083 "show": null
2084}
2085```
2086
2087**Options**
2088
20891. Show scrollbar in project panel
2090
2091```json
2092{
2093 "scrollbar": {
2094 "show": "always"
2095 }
2096}
2097```
2098
20992. Hide scrollbar in project panel
2100
2101```json
2102{
2103 "scrollbar": {
2104 "show": "never"
2105 }
2106}
2107```
2108
2109## Assistant Panel
2110
2111- Description: Customize assistant panel
2112- Setting: `assistant`
2113- Default:
2114
2115```json
2116"assistant": {
2117 "enabled": true,
2118 "button": true,
2119 "dock": "right",
2120 "default_width": 640,
2121 "default_height": 320,
2122 "provider": "openai",
2123 "version": "1",
2124},
2125```
2126
2127## Outline Panel
2128
2129- Description: Customize outline Panel
2130- Setting: `outline_panel`
2131- Default:
2132
2133```json
2134"outline_panel": {
2135 "button": true,
2136 "default_width": 240,
2137 "dock": "left",
2138 "file_icons": true,
2139 "folder_icons": true,
2140 "git_status": true,
2141 "indent_size": 20,
2142 "auto_reveal_entries": true,
2143 "auto_fold_dirs": true,
2144}
2145```
2146
2147## Calls
2148
2149- Description: Customize behavior when participating in a call
2150- Setting: `calls`
2151- Default:
2152
2153```json
2154"calls": {
2155 // Join calls with the microphone live by default
2156 "mute_on_join": false,
2157 // Share your project when you are the first to join a channel
2158 "share_on_join": false
2159},
2160```
2161
2162## Unnecessary Code Fade
2163
2164- Description: How much to fade out unused code.
2165- Setting: `unnecessary_code_fade`
2166- Default: `0.3`
2167
2168**Options**
2169
2170Float values between `0.0` and `0.9`, where:
2171
2172- `0.0` means no fading (unused code looks the same as used code)
2173- `0.9` means maximum fading (unused code is very faint but still visible)
2174
2175**Example**
2176
2177```json
2178{
2179 "unnecessary_code_fade": 0.5
2180}
2181```
2182
2183## UI Font Size
2184
2185- Description: The default font size for text in the UI.
2186- Setting: `ui_font_size`
2187- Default: `16`
2188
2189**Options**
2190
2191`integer` values from `6` to `100` pixels (inclusive)
2192
2193## An example configuration:
2194
2195```json
2196// ~/.config/zed/settings.json
2197{
2198 "theme": "cave-light",
2199 "tab_size": 2,
2200 "preferred_line_length": 80,
2201 "soft_wrap": "none",
2202
2203 "buffer_font_size": 18,
2204 "buffer_font_family": "Zed Plex Mono",
2205
2206 "autosave": "on_focus_change",
2207 "format_on_save": "off",
2208 "vim_mode": false,
2209 "projects_online_by_default": true,
2210 "terminal": {
2211 "font_family": "FiraCode Nerd Font Mono",
2212 "blinking": "off"
2213 },
2214 "languages": {
2215 "C": {
2216 "format_on_save": "language_server",
2217 "preferred_line_length": 64,
2218 "soft_wrap": "preferred_line_length"
2219 }
2220 }
2221}
2222```