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