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