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## Network Proxy
1065
1066- Description: Configure a network proxy for Zed.
1067- Setting: `proxy`
1068- Default: `null`
1069
1070**Options**
1071
1072The proxy setting must contain a URL to the proxy.
1073
1074The following URI schemes are supported:
1075
1076- `http`
1077- `https`
1078- `socks4`
1079- `socks4a`
1080- `socks5`
1081- `socks5h`
1082
1083`http` will be used when no scheme is specified.
1084
1085By 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`.
1086
1087For example, to set an `http` proxy, add the following to your settings:
1088
1089```json
1090{
1091 "proxy": "http://127.0.0.1:10809"
1092}
1093```
1094
1095Or to set a `socks5` proxy:
1096
1097```json
1098{
1099 "proxy": "socks5://localhost:10808"
1100}
1101```
1102
1103## Preview tabs
1104
1105- Description:
1106 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. \
1107 There are several ways to convert a preview tab into a regular tab:
1108
1109 - Double-clicking on the file
1110 - Double-clicking on the tab header
1111 - Using the `project_panel::OpenPermanent` action
1112 - Editing the file
1113 - Dragging the file to a different pane
1114
1115- Setting: `preview_tabs`
1116- Default:
1117
1118```json
1119"preview_tabs": {
1120 "enabled": true,
1121 "enable_preview_from_file_finder": false,
1122 "enable_preview_from_code_navigation": false,
1123}
1124```
1125
1126### Enable preview from file finder
1127
1128- Description: Determines whether to open files in preview mode when selected from the file finder.
1129- Setting: `enable_preview_from_file_finder`
1130- Default: `false`
1131
1132**Options**
1133
1134`boolean` values
1135
1136### Enable preview from code navigation
1137
1138- Description: Determines whether a preview tab gets replaced when code navigation is used to navigate away from the tab.
1139- Setting: `enable_preview_from_code_navigation`
1140- Default: `false`
1141
1142**Options**
1143
1144`boolean` values
1145
1146## Preferred Line Length
1147
1148- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
1149- Setting: `preferred_line_length`
1150- Default: `80`
1151
1152**Options**
1153
1154`integer` values
1155
1156## Projects Online By Default
1157
1158- Description: Whether or not to show the online projects view by default.
1159- Setting: `projects_online_by_default`
1160- Default: `true`
1161
1162**Options**
1163
1164`boolean` values
1165
1166## Remove Trailing Whitespace On Save
1167
1168- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
1169- Setting: `remove_trailing_whitespace_on_save`
1170- Default: `true`
1171
1172**Options**
1173
1174`boolean` values
1175
1176## Search
1177
1178- Description: Search options to enable by default when opening new project and buffer searches.
1179- Setting: `search`
1180- Default:
1181
1182```json
1183"search": {
1184 "whole_word": false,
1185 "case_sensitive": false,
1186 "include_ignored": false,
1187 "regex": false
1188},
1189```
1190
1191## Show Call Status Icon
1192
1193- Description: Whether or not to show the call status icon in the status bar.
1194- Setting: `show_call_status_icon`
1195- Default: `true`
1196
1197**Options**
1198
1199`boolean` values
1200
1201## Show Completions On Input
1202
1203- Description: Whether or not to show completions as you type.
1204- Setting: `show_completions_on_input`
1205- Default: `true`
1206
1207**Options**
1208
1209`boolean` values
1210
1211## Show Completion Documentation
1212
1213- Description: Whether to display inline and alongside documentation for items in the completions menu.
1214- Setting: `show_completion_documentation`
1215- Default: `true`
1216
1217**Options**
1218
1219`boolean` values
1220
1221## Completion Documentation Debounce Delay
1222
1223- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
1224- Setting: `completion_documentation_secondary_query_debounce`
1225- Default: `300` ms
1226
1227**Options**
1228
1229`integer` values
1230
1231## Show Inline Completions
1232
1233- Description: Whether to show inline completions as you type or manually by triggering `editor::ShowInlineCompletion`.
1234- Setting: `show_inline_completions`
1235- Default: `true`
1236
1237**Options**
1238
1239`boolean` values
1240
1241## Show Whitespaces
1242
1243- Description: Whether or not to show render whitespace characters in the editor.
1244- Setting: `show_whitespaces`
1245- Default: `selection`
1246
1247**Options**
1248
12491. `all`
12502. `selection`
12513. `none`
12524. `boundary`
1253
1254## Soft Wrap
1255
1256- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
1257- Setting: `soft_wrap`
1258- Default: `prefer_line`
1259
1260**Options**
1261
12621. `none` to stop the soft-wrapping
12632. `prefer_line` to avoid wrapping generally, unless the line is too long
12643. `editor_width` to wrap lines that overflow the editor width
12654. `preferred_line_length` to wrap lines that overflow `preferred_line_length` config value
1266
1267## Wrap Guides (Vertical Rulers)
1268
1269- Description: Where to display vertical rulers as wrap-guides. Disable by setting `show_wrap_guides` to `false`.
1270- Setting: `wrap_guides`
1271- Default: []
1272
1273**Options**
1274
1275List of `integer` column numbers
1276
1277## Tab Size
1278
1279- Description: The number of spaces to use for each tab character.
1280- Setting: `tab_size`
1281- Default: `4`
1282
1283**Options**
1284
1285`integer` values
1286
1287## Telemetry
1288
1289- Description: Control what info is collected by Zed.
1290- Setting: `telemetry`
1291- Default:
1292
1293```json
1294"telemetry": {
1295 "diagnostics": true,
1296 "metrics": true
1297},
1298```
1299
1300**Options**
1301
1302### Diagnostics
1303
1304- Description: Setting for sending debug-related data, such as crash reports.
1305- Setting: `diagnostics`
1306- Default: `true`
1307
1308**Options**
1309
1310`boolean` values
1311
1312### Metrics
1313
1314- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
1315- Setting: `metrics`
1316- Default: `true`
1317
1318**Options**
1319
1320`boolean` values
1321
1322## Terminal
1323
1324- Description: Configuration for the terminal.
1325- Setting: `terminal`
1326- Default:
1327
1328```json
1329{
1330 "terminal": {
1331 "alternate_scroll": "off",
1332 "blinking": "terminal_controlled",
1333 "copy_on_select": false,
1334 "dock": "bottom",
1335 "detect_venv": {
1336 "on": {
1337 "directories": [".env", "env", ".venv", "venv"],
1338 "activate_script": "default"
1339 }
1340 }
1341 "env": {},
1342 "font_family": null,
1343 "font_features": null,
1344 "font_size": null,
1345 "line_height": "comfortable",
1346 "option_as_meta": true,
1347 "button": false,
1348 "shell": {},
1349 "toolbar": {
1350 "title": true
1351 },
1352 "working_directory": "current_project_directory"
1353 }
1354}
1355```
1356
1357### Terminal: Dock
1358
1359- Description: Control the position of the dock
1360- Setting: `dock`
1361- Default: `bottom`
1362
1363**Options**
1364
1365`"bottom"`, `"left"` or `"right"`
1366
1367### Terminal: Alternate Scroll
1368
1369- 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.
1370- Setting: `alternate_scroll`
1371- Default: `off`
1372
1373**Options**
1374
13751. Default alternate scroll mode to on
1376
1377```json
1378{
1379 "terminal": {
1380 "alternate_scroll": "on"
1381 }
1382}
1383```
1384
13852. Default alternate scroll mode to off
1386
1387```json
1388{
1389 "terminal": {
1390 "alternate_scroll": "off"
1391 }
1392}
1393```
1394
1395### Terminal: Blinking
1396
1397- Description: Set the cursor blinking behavior in the terminal
1398- Setting: `blinking`
1399- Default: `terminal_controlled`
1400
1401**Options**
1402
14031. Never blink the cursor, ignore the terminal mode
1404
1405```json
1406{
1407 "terminal": {
1408 "blinking": "off"
1409 }
1410}
1411```
1412
14132. Default the cursor blink to off, but allow the terminal to turn blinking on
1414
1415```json
1416{
1417 "terminal": {
1418 "blinking": "terminal_controlled"
1419 }
1420}
1421```
1422
14233. Always blink the cursor, ignore the terminal mode
1424
1425```json
1426{
1427 "terminal": {
1428 "blinking": "on"
1429 }
1430}
1431```
1432
1433### Terminal: Copy On Select
1434
1435- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
1436- Setting: `copy_on_select`
1437- Default: `false`
1438
1439**Options**
1440
1441`boolean` values
1442
1443**Example**
1444
1445```json
1446{
1447 "terminal": {
1448 "copy_on_select": true
1449 }
1450}
1451```
1452
1453### Terminal: Env
1454
1455- 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
1456- Setting: `env`
1457- Default: `{}`
1458
1459**Example**
1460
1461```json
1462{
1463 "terminal": {
1464 "env": {
1465 "ZED": "1",
1466 "KEY": "value1:value2"
1467 }
1468 }
1469}
1470```
1471
1472### Terminal: Font Size
1473
1474- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
1475- Setting: `font_size`
1476- Default: `null`
1477
1478**Options**
1479
1480`integer` values
1481
1482```json
1483{
1484 "terminal": {
1485 "font_size": 15
1486 }
1487}
1488```
1489
1490### Terminal: Font Family
1491
1492- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
1493- Setting: `font_family`
1494- Default: `null`
1495
1496**Options**
1497
1498The name of any font family installed on the user's system
1499
1500```json
1501{
1502 "terminal": {
1503 "font_family": "Berkeley Mono"
1504 }
1505}
1506```
1507
1508### Terminal: Font Features
1509
1510- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
1511- Setting: `font_features`
1512- Default: `null`
1513- Platform: macOS and Windows.
1514
1515**Options**
1516
1517See Buffer Font Features
1518
1519```json
1520{
1521 "terminal": {
1522 "font_features": {
1523 "calt": false
1524 // See Buffer Font Features for more features
1525 }
1526 }
1527}
1528```
1529
1530### Terminal: Line Height
1531
1532- Description: Set the terminal's line height.
1533- Setting: `line_height`
1534- Default: `comfortable`
1535
1536**Options**
1537
15381. Use a line height that's `comfortable` for reading, 1.618. (default)
1539
1540```json
1541{
1542 "terminal": {
1543 "line_height": "comfortable"
1544 }
1545}
1546```
1547
15482. Use a `standard` line height, 1.3. This option is useful for TUIs, particularly if they use box characters
1549
1550```json
1551{
1552 "terminal": {
1553 "line_height": "standard"
1554 }
1555}
1556```
1557
15583. Use a custom line height.
1559
1560```json
1561{
1562 "terminal": {
1563 "line_height": {
1564 "custom": 2
1565 }
1566 }
1567}
1568```
1569
1570### Terminal: Option As Meta
1571
1572- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
1573- Setting: `option_as_meta`
1574- Default: `true`
1575
1576**Options**
1577
1578`boolean` values
1579
1580```json
1581{
1582 "terminal": {
1583 "option_as_meta": true
1584 }
1585}
1586```
1587
1588### Terminal: Shell
1589
1590- Description: What shell to use when launching the terminal.
1591- Setting: `shell`
1592- Default: `system`
1593
1594**Options**
1595
15961. Use the system's default terminal configuration (usually the `/etc/passwd` file).
1597
1598```json
1599{
1600 "terminal": {
1601 "shell": "system"
1602 }
1603}
1604```
1605
16062. A program to launch:
1607
1608```json
1609{
1610 "terminal": {
1611 "shell": {
1612 "program": "sh"
1613 }
1614 }
1615}
1616```
1617
16183. A program with arguments:
1619
1620```json
1621{
1622 "terminal": {
1623 "shell": {
1624 "with_arguments": {
1625 "program": "/bin/bash",
1626 "args": ["--login"]
1627 }
1628 }
1629 }
1630}
1631```
1632
1633## Terminal: Detect Virtual Environments {#terminal-detect_venv}
1634
1635- 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
1636- Setting: `detect_venv`
1637- Default:
1638
1639```json
1640{
1641 "terminal":
1642 "detect_venv": {
1643 "on": {
1644 // Default directories to search for virtual environments, relative
1645 // to the current working directory. We recommend overriding this
1646 // in your project's settings, rather than globally.
1647 "directories": [".venv", "venv"],
1648 // Can also be `csh`, `fish`, and `nushell`
1649 "activate_script": "default"
1650 }
1651 }
1652 }
1653}
1654```
1655
1656Disable with:
1657
1658```json
1659{
1660 "terminal":
1661 "detect_venv": "off"
1662 }
1663}
1664```
1665
1666## Terminal: Toolbar
1667
1668- Description: Whether or not to show various elements in the terminal toolbar. It only affects terminals placed in the editor pane.
1669- Setting: `toolbar`
1670- Default:
1671
1672```json
1673{
1674 "terminal": {
1675 "toolbar": {
1676 "title": true
1677 }
1678 }
1679}
1680```
1681
1682**Options**
1683
1684At 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.
1685
1686### Terminal: Button
1687
1688- Description: Control to show or hide the terminal button in the status bar
1689- Setting: `button`
1690- Default: `true`
1691
1692**Options**
1693
1694`boolean` values
1695
1696```json
1697{
1698 "terminal": {
1699 "button": false
1700 }
1701}
1702```
1703
1704### Terminal: Working Directory
1705
1706- Description: What working directory to use when launching the terminal.
1707- Setting: `working_directory`
1708- Default: `"current_project_directory"`
1709
1710**Options**
1711
17121. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
1713
1714```json
1715{
1716 "terminal": {
1717 "working_directory": "current_project_directory"
1718 }
1719}
1720```
1721
17222. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
1723
1724```json
1725{
1726 "terminal": {
1727 "working_directory": "first_project_directory"
1728 }
1729}
1730```
1731
17323. Always use this platform's home directory (if we can find it)
1733
1734```json
1735{
1736 "terminal": {
1737 "working_directory": "always_home"
1738 }
1739}
1740```
1741
17424. 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.
1743
1744```json
1745{
1746 "terminal": {
1747 "working_directory": {
1748 "always": {
1749 "directory": "~/zed/projects/"
1750 }
1751 }
1752 }
1753}
1754```
1755
1756## Theme
1757
1758- 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.
1759- Setting: `theme`
1760- Default: `One Dark`
1761
1762### Theme Object
1763
1764- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
1765- Setting: `theme`
1766- Default:
1767
1768```json
1769"theme": {
1770 "mode": "system",
1771 "dark": "One Dark",
1772 "light": "One Light"
1773},
1774```
1775
1776### Mode
1777
1778- Description: Specify theme mode.
1779- Setting: `mode`
1780- Default: `system`
1781
1782**Options**
1783
17841. Set the theme to dark mode
1785
1786```json
1787{
1788 "mode": "dark"
1789}
1790```
1791
17922. Set the theme to light mode
1793
1794```json
1795{
1796 "mode": "light"
1797}
1798```
1799
18003. Set the theme to system mode
1801
1802```json
1803{
1804 "mode": "system"
1805}
1806```
1807
1808### Dark
1809
1810- Description: The name of the dark Zed theme to use for the UI.
1811- Setting: `dark`
1812- Default: `One Dark`
1813
1814**Options**
1815
1816Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1817
1818### Light
1819
1820- Description: The name of the light Zed theme to use for the UI.
1821- Setting: `light`
1822- Default: `One Light`
1823
1824**Options**
1825
1826Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1827
1828## Vim
1829
1830- Description: Whether or not to enable vim mode (work in progress).
1831- Setting: `vim_mode`
1832- Default: `false`
1833
1834## Project Panel
1835
1836- Description: Customize project panel
1837- Setting: `project_panel`
1838- Default:
1839
1840```json
1841{
1842 "project_panel": {
1843 "button": true,
1844 "default_width": 240,
1845 "dock": "left",
1846 "file_icons": true,
1847 "folder_icons": true,
1848 "git_status": true,
1849 "indent_size": 20,
1850 "auto_reveal_entries": true,
1851 "auto_fold_dirs": true,
1852 "scrollbar": {
1853 "show": "always"
1854 }
1855 }
1856}
1857```
1858
1859### Dock
1860
1861- Description: Control the position of the dock
1862- Setting: `dock`
1863- Default: `left`
1864
1865**Options**
1866
18671. Default dock position to left
1868
1869```json
1870{
1871 "dock": "left"
1872}
1873```
1874
18752. Default dock position to right
1876
1877```json
1878{
1879 "dock": "right"
1880}
1881```
1882
1883### Git Status
1884
1885- Description: Indicates newly created and updated files
1886- Setting: `git_status`
1887- Default: `true`
1888
1889**Options**
1890
18911. Default enable git status
1892
1893```json
1894{
1895 "git_status": true
1896}
1897```
1898
18992. Default disable git status
1900
1901```json
1902{
1903 "git_status": false
1904}
1905```
1906
1907### Default Width
1908
1909- Description: Customize default width taken by project panel
1910- Setting: `default_width`
1911- Default: N/A width in pixels (eg: 420)
1912
1913**Options**
1914
1915`boolean` values
1916
1917### Auto Reveal Entries
1918
1919- Description: Whether to reveal it in the project panel automatically, when a corresponding project entry becomes active. Gitignored entries are never auto revealed.
1920- Setting: `auto_reveal_entries`
1921- Default: `true`
1922
1923**Options**
1924
19251. Enable auto reveal entries
1926
1927```json
1928{
1929 "auto_reveal_entries": true
1930}
1931```
1932
19332. Disable auto reveal entries
1934
1935```json
1936{
1937 "auto_reveal_entries": false
1938}
1939```
1940
1941### Auto Fold Dirs
1942
1943- Description: Whether to fold directories automatically when directory has only one directory inside.
1944- Setting: `auto_fold_dirs`
1945- Default: `true`
1946
1947**Options**
1948
19491. Enable auto fold dirs
1950
1951```json
1952{
1953 "auto_fold_dirs": true
1954}
1955```
1956
19572. Disable auto fold dirs
1958
1959```json
1960{
1961 "auto_fold_dirs": false
1962}
1963```
1964
1965### Indent Size
1966
1967- Description: Amount of indentation (in pixels) for nested items.
1968- Setting: `indent_size`
1969- Default: `20`
1970
1971### Scrollbar
1972
1973- Description: Scrollbar related settings. Possible values: "always", "never".
1974- Setting: `scrollbar`
1975- Default:
1976
1977```json
1978"scrollbar": {
1979 "show": "always"
1980}
1981```
1982
1983**Options**
1984
19851. Show scrollbar in project panel
1986
1987```json
1988{
1989 "scrollbar": {
1990 "show": "always"
1991 }
1992}
1993```
1994
19952. Hide scrollbar in project panel
1996
1997```json
1998{
1999 "scrollbar": {
2000 "show": "never"
2001 }
2002}
2003```
2004
2005## Assistant Panel
2006
2007- Description: Customize assistant panel
2008- Setting: `assistant`
2009- Default:
2010
2011```json
2012"assistant": {
2013 "enabled": true,
2014 "button": true,
2015 "dock": "right",
2016 "default_width": 640,
2017 "default_height": 320,
2018 "provider": "openai",
2019 "version": "1",
2020},
2021```
2022
2023## Outline Panel
2024
2025- Description: Customize outline Panel
2026- Setting: `outline_panel`
2027- Default:
2028
2029```json
2030"outline_panel": {
2031 "button": true,
2032 "default_width": 240,
2033 "dock": "left",
2034 "file_icons": true,
2035 "folder_icons": true,
2036 "git_status": true,
2037 "indent_size": 20,
2038 "auto_reveal_entries": true,
2039 "auto_fold_dirs": true,
2040}
2041```
2042
2043## Calls
2044
2045- Description: Customize behavior when participating in a call
2046- Setting: `calls`
2047- Default:
2048
2049```json
2050"calls": {
2051 // Join calls with the microphone live by default
2052 "mute_on_join": false,
2053 // Share your project when you are the first to join a channel
2054 "share_on_join": false
2055},
2056```
2057
2058## Unnecessary Code Fade
2059
2060- Description: How much to fade out unused code.
2061- Setting: `unnecessary_code_fade`
2062- Default: `0.3`
2063
2064**Options**
2065
2066Float values between `0.0` and `0.9`, where:
2067
2068- `0.0` means no fading (unused code looks the same as used code)
2069- `0.9` means maximum fading (unused code is very faint but still visible)
2070
2071**Example**
2072
2073```json
2074{
2075 "unnecessary_code_fade": 0.5
2076}
2077```
2078
2079## An example configuration:
2080
2081```json
2082// ~/.config/zed/settings.json
2083{
2084 "theme": "cave-light",
2085 "tab_size": 2,
2086 "preferred_line_length": 80,
2087 "soft_wrap": "none",
2088
2089 "buffer_font_size": 18,
2090 "buffer_font_family": "Zed Plex Mono",
2091
2092 "autosave": "on_focus_change",
2093 "format_on_save": "off",
2094 "vim_mode": false,
2095 "projects_online_by_default": true,
2096 "terminal": {
2097 "font_family": "FiraCode Nerd Font Mono",
2098 "blinking": "off"
2099 },
2100 "languages": {
2101 "C": {
2102 "format_on_save": "language_server",
2103 "preferred_line_length": 64,
2104 "soft_wrap": "preferred_line_length"
2105 }
2106 }
2107}
2108```