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## Show Call Status Icon
1138
1139- Description: Whether or not to show the call status icon in the status bar.
1140- Setting: `show_call_status_icon`
1141- Default: `true`
1142
1143**Options**
1144
1145`boolean` values
1146
1147## Show Completions On Input
1148
1149- Description: Whether or not to show completions as you type.
1150- Setting: `show_completions_on_input`
1151- Default: `true`
1152
1153**Options**
1154
1155`boolean` values
1156
1157## Show Completion Documentation
1158
1159- Description: Whether to display inline and alongside documentation for items in the completions menu.
1160- Setting: `show_completion_documentation`
1161- Default: `true`
1162
1163**Options**
1164
1165`boolean` values
1166
1167## Completion Documentation Debounce Delay
1168
1169- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
1170- Setting: `completion_documentation_secondary_query_debounce`
1171- Default: `300` ms
1172
1173**Options**
1174
1175`integer` values
1176
1177## Show Inline Completions
1178
1179- Description: Whether to show inline completions as you type or manually by triggering `editor::ShowInlineCompletion`.
1180- Setting: `show_inline_completions`
1181- Default: `true`
1182
1183**Options**
1184
1185`boolean` values
1186
1187## Show Whitespaces
1188
1189- Description: Whether or not to show render whitespace characters in the editor.
1190- Setting: `show_whitespaces`
1191- Default: `selection`
1192
1193**Options**
1194
11951. `all`
11962. `selection`
11973. `none`
11984. `boundary`
1199
1200## Soft Wrap
1201
1202- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
1203- Setting: `soft_wrap`
1204- Default: `prefer_line`
1205
1206**Options**
1207
12081. `none` to stop the soft-wrapping
12092. `prefer_line` to avoid wrapping generally, unless the line is too long
12103. `editor_width` to wrap lines that overflow the editor width
12114. `preferred_line_length` to wrap lines that overflow `preferred_line_length` config value
1212
1213## Wrap Guides (Vertical Rulers)
1214
1215- Description: Where to display vertical rulers as wrap-guides. Disable by setting `show_wrap_guides` to `false`.
1216- Setting: `wrap_guides`
1217- Default: []
1218
1219**Options**
1220
1221List of `integer` column numbers
1222
1223## Tab Size
1224
1225- Description: The number of spaces to use for each tab character.
1226- Setting: `tab_size`
1227- Default: `4`
1228
1229**Options**
1230
1231`integer` values
1232
1233## Telemetry
1234
1235- Description: Control what info is collected by Zed.
1236- Setting: `telemetry`
1237- Default:
1238
1239```json
1240"telemetry": {
1241 "diagnostics": true,
1242 "metrics": true
1243},
1244```
1245
1246**Options**
1247
1248### Diagnostics
1249
1250- Description: Setting for sending debug-related data, such as crash reports.
1251- Setting: `diagnostics`
1252- Default: `true`
1253
1254**Options**
1255
1256`boolean` values
1257
1258### Metrics
1259
1260- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
1261- Setting: `metrics`
1262- Default: `true`
1263
1264**Options**
1265
1266`boolean` values
1267
1268## Terminal
1269
1270- Description: Configuration for the terminal.
1271- Setting: `terminal`
1272- Default:
1273
1274```json
1275{
1276 "terminal": {
1277 "alternate_scroll": "off",
1278 "blinking": "terminal_controlled",
1279 "copy_on_select": false,
1280 "dock": "bottom",
1281 "detect_venv": {
1282 "on": {
1283 "directories": [".env", "env", ".venv", "venv"],
1284 "activate_script": "default"
1285 }
1286 }
1287 "env": {},
1288 "font_family": null,
1289 "font_features": null,
1290 "font_size": null,
1291 "line_height": "comfortable",
1292 "option_as_meta": true,
1293 "button": false,
1294 "shell": {},
1295 "toolbar": {
1296 "title": true
1297 },
1298 "working_directory": "current_project_directory"
1299 }
1300}
1301```
1302
1303### Terminal: Dock
1304
1305- Description: Control the position of the dock
1306- Setting: `dock`
1307- Default: `bottom`
1308
1309**Options**
1310
1311`"bottom"`, `"left"` or `"right"`
1312
1313### Terminal: Alternate Scroll
1314
1315- 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.
1316- Setting: `alternate_scroll`
1317- Default: `off`
1318
1319**Options**
1320
13211. Default alternate scroll mode to on
1322
1323```json
1324{
1325 "terminal": {
1326 "alternate_scroll": "on"
1327 }
1328}
1329```
1330
13312. Default alternate scroll mode to off
1332
1333```json
1334{
1335 "terminal": {
1336 "alternate_scroll": "off"
1337 }
1338}
1339```
1340
1341### Terminal: Blinking
1342
1343- Description: Set the cursor blinking behavior in the terminal
1344- Setting: `blinking`
1345- Default: `terminal_controlled`
1346
1347**Options**
1348
13491. Never blink the cursor, ignore the terminal mode
1350
1351```json
1352{
1353 "terminal": {
1354 "blinking": "off"
1355 }
1356}
1357```
1358
13592. Default the cursor blink to off, but allow the terminal to turn blinking on
1360
1361```json
1362{
1363 "terminal": {
1364 "blinking": "terminal_controlled"
1365 }
1366}
1367```
1368
13693. Always blink the cursor, ignore the terminal mode
1370
1371```json
1372{
1373 "terminal": {
1374 "blinking": "on"
1375 }
1376}
1377```
1378
1379### Terminal: Copy On Select
1380
1381- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
1382- Setting: `copy_on_select`
1383- Default: `false`
1384
1385**Options**
1386
1387`boolean` values
1388
1389**Example**
1390
1391```json
1392{
1393 "terminal": {
1394 "copy_on_select": true
1395 }
1396}
1397```
1398
1399### Terminal: Env
1400
1401- 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
1402- Setting: `env`
1403- Default: `{}`
1404
1405**Example**
1406
1407```json
1408{
1409 "terminal": {
1410 "env": {
1411 "ZED": "1",
1412 "KEY": "value1:value2"
1413 }
1414 }
1415}
1416```
1417
1418### Terminal: Font Size
1419
1420- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
1421- Setting: `font_size`
1422- Default: `null`
1423
1424**Options**
1425
1426`integer` values
1427
1428```json
1429{
1430 "terminal": {
1431 "font_size": 15
1432 }
1433}
1434```
1435
1436### Terminal: Font Family
1437
1438- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
1439- Setting: `font_family`
1440- Default: `null`
1441
1442**Options**
1443
1444The name of any font family installed on the user's system
1445
1446```json
1447{
1448 "terminal": {
1449 "font_family": "Berkeley Mono"
1450 }
1451}
1452```
1453
1454### Terminal: Font Features
1455
1456- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
1457- Setting: `font_features`
1458- Default: `null`
1459- Platform: macOS and Windows.
1460
1461**Options**
1462
1463See Buffer Font Features
1464
1465```jsonc
1466{
1467 "terminal": {
1468 "font_features": {
1469 "calt": false,
1470 // See Buffer Font Features for more features
1471 },
1472 },
1473}
1474```
1475
1476### Terminal: Line Height
1477
1478- Description: Set the terminal's line height.
1479- Setting: `line_height`
1480- Default: `comfortable`
1481
1482**Options**
1483
14841. Use a line height that's `comfortable` for reading, 1.618. (default)
1485
1486```jsonc
1487{
1488 "terminal": {
1489 "line_height": "comfortable",
1490 },
1491}
1492```
1493
14942. Use a `standard` line height, 1.3. This option is useful for TUIs, particularly if they use box characters
1495
1496```jsonc
1497{
1498 "terminal": {
1499 "line_height": "standard",
1500 },
1501}
1502```
1503
15043. Use a custom line height.
1505
1506```jsonc
1507{
1508 "terminal": {
1509 "line_height": {
1510 "custom": 2,
1511 },
1512 },
1513}
1514```
1515
1516### Terminal: Option As Meta
1517
1518- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
1519- Setting: `option_as_meta`
1520- Default: `true`
1521
1522**Options**
1523
1524`boolean` values
1525
1526```json
1527{
1528 "terminal": {
1529 "option_as_meta": true
1530 }
1531}
1532```
1533
1534### Terminal: Shell
1535
1536- Description: What shell to use when launching the terminal.
1537- Setting: `shell`
1538- Default: `system`
1539
1540**Options**
1541
15421. Use the system's default terminal configuration (usually the `/etc/passwd` file).
1543
1544```json
1545{
1546 "terminal": {
1547 "shell": "system"
1548 }
1549}
1550```
1551
15522. A program to launch:
1553
1554```json
1555{
1556 "terminal": {
1557 "shell": {
1558 "program": "sh"
1559 }
1560 }
1561}
1562```
1563
15643. A program with arguments:
1565
1566```json
1567{
1568 "terminal": {
1569 "shell": {
1570 "with_arguments": {
1571 "program": "/bin/bash",
1572 "args": ["--login"]
1573 }
1574 }
1575 }
1576}
1577```
1578
1579## Terminal: Detect Virtual Environments {#terminal-detect_venv}
1580
1581- 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
1582- Setting: `detect_venv`
1583- Default:
1584
1585```json
1586{
1587 "terminal":
1588 "detect_venv": {
1589 "on": {
1590 // Default directories to search for virtual environments, relative
1591 // to the current working directory. We recommend overriding this
1592 // in your project's settings, rather than globally.
1593 "directories": [".venv", "venv"],
1594 // Can also be `csh`, `fish`, and `nushell`
1595 "activate_script": "default"
1596 }
1597 }
1598 }
1599}
1600```
1601
1602Disable with:
1603
1604```json
1605{
1606 "terminal":
1607 "detect_venv": "off"
1608 }
1609}
1610```
1611
1612## Terminal: Toolbar
1613
1614- Description: Whether or not to show various elements in the terminal toolbar. It only affects terminals placed in the editor pane.
1615- Setting: `toolbar`
1616- Default:
1617
1618```json
1619{
1620 "terminal": {
1621 "toolbar": {
1622 "title": true
1623 }
1624 }
1625}
1626```
1627
1628**Options**
1629
1630At 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.
1631
1632### Terminal: Button
1633
1634- Description: Control to show or hide the terminal button in the status bar
1635- Setting: `button`
1636- Default: `true`
1637
1638**Options**
1639
1640`boolean` values
1641
1642```json
1643{
1644 "terminal": {
1645 "button": false
1646 }
1647}
1648```
1649
1650### Terminal: Working Directory
1651
1652- Description: What working directory to use when launching the terminal.
1653- Setting: `working_directory`
1654- Default: `"current_project_directory"`
1655
1656**Options**
1657
16581. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
1659
1660```json
1661{
1662 "terminal": {
1663 "working_directory": "current_project_directory"
1664 }
1665}
1666```
1667
16682. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
1669
1670```json
1671{
1672 "terminal": {
1673 "working_directory": "first_project_directory"
1674 }
1675}
1676```
1677
16783. Always use this platform's home directory (if we can find it)
1679
1680```json
1681{
1682 "terminal": {
1683 "working_directory": "always_home"
1684 }
1685}
1686```
1687
16884. 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.
1689
1690```json
1691{
1692 "terminal": {
1693 "working_directory": {
1694 "always": {
1695 "directory": "~/zed/projects/"
1696 }
1697 }
1698 }
1699}
1700```
1701
1702## Theme
1703
1704- 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.
1705- Setting: `theme`
1706- Default: `One Dark`
1707
1708### Theme Object
1709
1710- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
1711- Setting: `theme`
1712- Default:
1713
1714```json
1715"theme": {
1716 "mode": "system",
1717 "dark": "One Dark",
1718 "light": "One Light"
1719},
1720```
1721
1722### Mode
1723
1724- Description: Specify theme mode.
1725- Setting: `mode`
1726- Default: `system`
1727
1728**Options**
1729
17301. Set the theme to dark mode
1731
1732```json
1733{
1734 "mode": "dark"
1735}
1736```
1737
17382. Set the theme to light mode
1739
1740```json
1741{
1742 "mode": "light"
1743}
1744```
1745
17463. Set the theme to system mode
1747
1748```json
1749{
1750 "mode": "system"
1751}
1752```
1753
1754### Dark
1755
1756- Description: The name of the dark Zed theme to use for the UI.
1757- Setting: `dark`
1758- Default: `One Dark`
1759
1760**Options**
1761
1762Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1763
1764### Light
1765
1766- Description: The name of the light Zed theme to use for the UI.
1767- Setting: `light`
1768- Default: `One Light`
1769
1770**Options**
1771
1772Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1773
1774## Vim
1775
1776- Description: Whether or not to enable vim mode (work in progress).
1777- Setting: `vim_mode`
1778- Default: `false`
1779
1780## Project Panel
1781
1782- Description: Customize project panel
1783- Setting: `project_panel`
1784- Default:
1785
1786```json
1787{
1788 "project_panel": {
1789 "button": true,
1790 "default_width": 240,
1791 "dock": "left",
1792 "file_icons": true,
1793 "folder_icons": true,
1794 "git_status": true,
1795 "indent_size": 20,
1796 "auto_reveal_entries": true,
1797 "auto_fold_dirs": true,
1798 "scrollbar": {
1799 "show": "always"
1800 }
1801 }
1802}
1803```
1804
1805### Dock
1806
1807- Description: Control the position of the dock
1808- Setting: `dock`
1809- Default: `left`
1810
1811**Options**
1812
18131. Default dock position to left
1814
1815```json
1816{
1817 "dock": "left"
1818}
1819```
1820
18212. Default dock position to right
1822
1823```json
1824{
1825 "dock": "right"
1826}
1827```
1828
1829### Git Status
1830
1831- Description: Indicates newly created and updated files
1832- Setting: `git_status`
1833- Default: `true`
1834
1835**Options**
1836
18371. Default enable git status
1838
1839```json
1840{
1841 "git_status": true
1842}
1843```
1844
18452. Default disable git status
1846
1847```json
1848{
1849 "git_status": false
1850}
1851```
1852
1853### Default Width
1854
1855- Description: Customize default width taken by project panel
1856- Setting: `default_width`
1857- Default: N/A width in pixels (eg: 420)
1858
1859**Options**
1860
1861`boolean` values
1862
1863### Auto Reveal Entries
1864
1865- Description: Whether to reveal it in the project panel automatically, when a corresponding project entry becomes active. Gitignored entries are never auto revealed.
1866- Setting: `auto_reveal_entries`
1867- Default: `true`
1868
1869**Options**
1870
18711. Enable auto reveal entries
1872
1873```json
1874{
1875 "auto_reveal_entries": true
1876}
1877```
1878
18792. Disable auto reveal entries
1880
1881```json
1882{
1883 "auto_reveal_entries": false
1884}
1885```
1886
1887### Auto Fold Dirs
1888
1889- Description: Whether to fold directories automatically when directory has only one directory inside.
1890- Setting: `auto_fold_dirs`
1891- Default: `true`
1892
1893**Options**
1894
18951. Enable auto fold dirs
1896
1897```json
1898{
1899 "auto_fold_dirs": true
1900}
1901```
1902
19032. Disable auto fold dirs
1904
1905```json
1906{
1907 "auto_fold_dirs": false
1908}
1909```
1910
1911### Indent Size
1912
1913- Description: Amount of indentation (in pixels) for nested items.
1914- Setting: `indent_size`
1915- Default: `20`
1916
1917### Scrollbar
1918
1919- Description: Scrollbar related settings. Possible values: "always", "never".
1920- Setting: `scrollbar`
1921- Default:
1922
1923```json
1924"scrollbar": {
1925 "show": "always"
1926}
1927```
1928
1929**Options**
1930
19311. Show scrollbar in project panel
1932
1933```json
1934{
1935 "scrollbar": {
1936 "show": "always"
1937 }
1938}
1939```
1940
19412. Hide scrollbar in project panel
1942
1943```json
1944{
1945 "scrollbar": {
1946 "show": "never"
1947 }
1948}
1949```
1950
1951## Assistant Panel
1952
1953- Description: Customize assistant panel
1954- Setting: `assistant`
1955- Default:
1956
1957```json
1958"assistant": {
1959 "enabled": true,
1960 "button": true,
1961 "dock": "right",
1962 "default_width": 640,
1963 "default_height": 320,
1964 "provider": "openai",
1965 "version": "1",
1966},
1967```
1968
1969## Outline Panel
1970
1971- Description: Customize outline Panel
1972- Setting: `outline_panel`
1973- Default:
1974
1975```json
1976"outline_panel": {
1977 "button": true,
1978 "default_width": 240,
1979 "dock": "left",
1980 "file_icons": true,
1981 "folder_icons": true,
1982 "git_status": true,
1983 "indent_size": 20,
1984 "auto_reveal_entries": true,
1985 "auto_fold_dirs": true,
1986}
1987```
1988
1989## Calls
1990
1991- Description: Customize behavior when participating in a call
1992- Setting: `calls`
1993- Default:
1994
1995```json
1996"calls": {
1997 // Join calls with the microphone live by default
1998 "mute_on_join": false,
1999 // Share your project when you are the first to join a channel
2000 "share_on_join": false
2001},
2002```
2003
2004## Unnecessary Code Fade
2005
2006- Description: How much to fade out unused code.
2007- Setting: `unnecessary_code_fade`
2008- Default: `0.3`
2009
2010**Options**
2011
2012Float values between `0.0` and `0.9`, where:
2013
2014- `0.0` means no fading (unused code looks the same as used code)
2015- `0.9` means maximum fading (unused code is very faint but still visible)
2016
2017**Example**
2018
2019```json
2020{
2021 "unnecessary_code_fade": 0.5
2022}
2023```
2024
2025## An example configuration:
2026
2027```json
2028// ~/.config/zed/settings.json
2029{
2030 "theme": "cave-light",
2031 "tab_size": 2,
2032 "preferred_line_length": 80,
2033 "soft_wrap": "none",
2034
2035 "buffer_font_size": 18,
2036 "buffer_font_family": "Zed Plex Mono",
2037
2038 "autosave": "on_focus_change",
2039 "format_on_save": "off",
2040 "vim_mode": false,
2041 "projects_online_by_default": true,
2042 "terminal": {
2043 "font_family": "FiraCode Nerd Font Mono",
2044 "blinking": "off"
2045 },
2046 "languages": {
2047 "C": {
2048 "format_on_save": "language_server",
2049 "preferred_line_length": 64,
2050 "soft_wrap": "preferred_line_length"
2051 }
2052 }
2053}
2054```