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