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