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 underline that runs along the following character:
317
318```json
319"cursor_shape": "underline"
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
579To override settings for a language, add an entry for that language server's name to the `lsp` value. Example:
580
581```json
582"lsp": {
583 "rust-analyzer": {
584 "initialization_options": {
585 "check": {
586 "command": "clippy" // rust-analyzer.check.command (default: "check")
587 }
588 }
589 }
590}
591```
592
593## Format On Save
594
595- Description: Whether or not to perform a buffer format before saving.
596- Setting: `format_on_save`
597- Default: `on`
598
599**Options**
600
6011. `on`, enables format on save obeying `formatter` setting:
602
603```json
604{
605 "format_on_save": "on"
606}
607```
608
6092. `off`, disables format on save:
610
611```json
612{
613 "format_on_save": "off"
614}
615```
616
617## Formatter
618
619- Description: How to perform a buffer format.
620- Setting: `formatter`
621- Default: `auto`
622
623**Options**
624
6251. To use the current language server, use `"language_server"`:
626
627```json
628{
629 "formatter": "language_server"
630}
631```
632
6332. 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):
634
635```json
636{
637 "formatter": {
638 "external": {
639 "command": "sed",
640 "arguments": ["-e", "s/ *$//"]
641 }
642 }
643}
644```
645
6463. Or to use code actions provided by the connected language servers, use `"code_actions"`:
647
648```json
649{
650 "formatter": {
651 "code_actions": {
652 // Use ESLint's --fix:
653 "source.fixAll.eslint": true,
654 // Organize imports on save:
655 "source.organizeImports": true
656 }
657 }
658}
659```
660
6614. Or to use multiple formatters consecutively, use an array of formatters:
662
663```json
664{
665 "formatter": [
666 {"language_server": {"name": "rust-analyzer"}},
667 {"external": {
668 "command": "sed",
669 "arguments": ["-e", "s/ *$//"]
670 }
671 ]
672}
673```
674
675Here `rust-analyzer` will be used first to format the code, followed by a call of sed.
676If any of the formatters fails, the subsequent ones will still be executed.
677
678## Code Actions On Format
679
680- Description: The code actions to perform with the primary language server when formatting the buffer.
681- Setting: `code_actions_on_format`
682- Default: `{}`, except for Go it's `{ "source.organizeImports": true }`
683
684**Examples**
685
686<!--
687TBD: Add Python Ruff source.organizeImports example
688-->
689
6901. Organize imports on format in TypeScript and TSX buffers:
691
692```json
693{
694 "languages": {
695 "TypeScript": {
696 "code_actions_on_format": {
697 "source.organizeImports": true
698 }
699 },
700 "TSX": {
701 "code_actions_on_format": {
702 "source.organizeImports": true
703 }
704 }
705 }
706}
707```
708
7092. Run ESLint `fixAll` code action when formatting:
710
711```json
712{
713 "languages": {
714 "JavaScript": {
715 "code_actions_on_format": {
716 "source.fixAll.eslint": true
717 }
718 }
719 }
720}
721```
722
7233. Run only a single ESLint rule when using `fixAll`:
724
725```json
726{
727 "languages": {
728 "JavaScript": {
729 "code_actions_on_format": {
730 "source.fixAll.eslint": true
731 }
732 }
733 },
734 "lsp": {
735 "eslint": {
736 "settings": {
737 "codeActionOnSave": {
738 "rules": ["import/order"]
739 }
740 }
741 }
742 }
743}
744```
745
746## Auto close
747
748- Description: Whether to automatically add matching closing characters when typing opening parenthesis, bracket, brace, single or double quote characters.
749- Setting: `use_autoclose`
750- Default: `true`
751
752**Options**
753
754`boolean` values
755
756## Always Treat Brackets As Autoclosed
757
758- Description: Controls how the editor handles the autoclosed characters.
759- Setting: `always_treat_brackets_as_autoclosed`
760- Default: `false`
761
762**Options**
763
764`boolean` values
765
766**Example**
767
768If the setting is set to `true`:
769
7701. Enter in the editor: `)))`
7712. Move the cursor to the start: `^)))`
7723. Enter again: `)))`
773
774The result is still `)))` and not `))))))`, which is what it would be by default.
775
776## File Types
777
778- Setting: `file_types`
779- Description: Configure how Zed selects a language for a file based on its filename or extension. Supports glob entries.
780- Default: `{}`
781
782**Examples**
783
784To interpret all `.c` files as C++, files called `MyLockFile` as TOML and files starting with `Dockerfile` as Dockerfile:
785
786```json
787{
788 "file_types": {
789 "C++": ["c"],
790 "TOML": ["MyLockFile"],
791 "Dockerfile": ["Dockerfile*"]
792 }
793}
794```
795
796## Git
797
798- Description: Configuration for git-related features.
799- Setting: `git`
800- Default:
801
802```json
803{
804 "git": {
805 "git_gutter": "tracked_files",
806 "inline_blame": {
807 "enabled": true
808 }
809 }
810}
811```
812
813### Git Gutter
814
815- Description: Whether or not to show the git gutter.
816- Setting: `git_gutter`
817- Default: `tracked_files`
818
819**Options**
820
8211. Show git gutter in tracked files
822
823```json
824{
825 "git": {
826 "git_gutter": "tracked_files"
827 }
828}
829```
830
8312. Hide git gutter
832
833```json
834{
835 "git": {
836 "git_gutter": "hide"
837 }
838}
839```
840
841### Indent Guides
842
843- Description: Configuration related to indent guides. Indent guides can be configured separately for each language.
844- Setting: `indent_guides`
845- Default:
846
847```json
848{
849 "indent_guides": {
850 "enabled": true,
851 "line_width": 1,
852 "active_line_width": 1,
853 "coloring": "fixed",
854 "background_coloring": "disabled"
855 }
856}
857```
858
859**Options**
860
8611. Disable indent guides
862
863```json
864{
865 "indent_guides": {
866 "enabled": false
867 }
868}
869```
870
8712. Enable indent guides for a specific language.
872
873```json
874{
875 "languages": {
876 "Python": {
877 "indent_guides": {
878 "enabled": true
879 }
880 }
881 }
882}
883```
884
8853. Enable indent aware coloring ("rainbow indentation").
886 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.
887
888```json
889{
890 "indent_guides": {
891 "enabled": true,
892 "coloring": "indent_aware"
893 }
894}
895```
896
8974. Enable indent aware background coloring ("rainbow indentation").
898 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.
899
900```json
901{
902 "indent_guides": {
903 "enabled": true,
904 "coloring": "indent_aware",
905 "background_coloring": "indent_aware"
906 }
907}
908```
909
910### Inline Git Blame
911
912- Description: Whether or not to show git blame information inline, on the currently focused line.
913- Setting: `inline_blame`
914- Default:
915
916```json
917{
918 "git": {
919 "inline_blame": {
920 "enabled": true
921 }
922 }
923}
924```
925
926**Options**
927
9281. Disable inline git blame:
929
930```json
931{
932 "git": {
933 "inline_blame": {
934 "enabled": false
935 }
936 }
937}
938```
939
9402. Only show inline git blame after a delay (that starts after cursor stops moving):
941
942```json
943{
944 "git": {
945 "inline_blame": {
946 "enabled": true,
947 "delay_ms": 500
948 }
949 }
950}
951```
952
953## Hard Tabs
954
955- Description: Whether to indent lines using tab characters or multiple spaces.
956- Setting: `hard_tabs`
957- Default: `false`
958
959**Options**
960
961`boolean` values
962
963## Hover Popover Enabled
964
965- Description: Whether or not to show the informational hover box when moving the mouse over symbols in the editor.
966- Setting: `hover_popover_enabled`
967- Default: `true`
968
969**Options**
970
971`boolean` values
972
973## Inlay hints
974
975- Description: Configuration for displaying extra text with hints in the editor.
976- Setting: `inlay_hints`
977- Default:
978
979```json
980"inlay_hints": {
981 "enabled": false,
982 "show_type_hints": true,
983 "show_parameter_hints": true,
984 "show_other_hints": true,
985 "show_background": false,
986 "edit_debounce_ms": 700,
987 "scroll_debounce_ms": 50
988}
989```
990
991**Options**
992
993Inlay hints querying consists of two parts: editor (client) and LSP server.
994With 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.
995At 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.
996
997The following languages have inlay hints preconfigured by Zed:
998
999- [Go](https://docs.zed.dev/languages/go)
1000- [Rust](https://docs.zed.dev/languages/rust)
1001- [Svelte](https://docs.zed.dev/languages/svelte)
1002- [Typescript](https://docs.zed.dev/languages/typescript)
1003
1004Use the `lsp` section for the server configuration. Examples are provided in the corresponding language documentation.
1005
1006Hints are not instantly queried in Zed, two kinds of debounces are used, either may be set to 0 to be disabled.
1007Settings-related hint updates are not debounced.
1008
1009## Journal
1010
1011- Description: Configuration for the journal.
1012- Setting: `journal`
1013- Default:
1014
1015```json
1016"journal": {
1017 "path": "~",
1018 "hour_format": "hour12"
1019}
1020```
1021
1022### Path
1023
1024- Description: The path of the directory where journal entries are stored.
1025- Setting: `path`
1026- Default: `~`
1027
1028**Options**
1029
1030`string` values
1031
1032### Hour Format
1033
1034- Description: The format to use for displaying hours in the journal.
1035- Setting: `hour_format`
1036- Default: `hour12`
1037
1038**Options**
1039
10401. 12-hour format:
1041
1042```json
1043{
1044 "hour_format": "hour12"
1045}
1046```
1047
10482. 24-hour format:
1049
1050```json
1051{
1052 "hour_format": "hour24"
1053}
1054```
1055
1056## Languages
1057
1058- Description: Configuration for specific languages.
1059- Setting: `languages`
1060- Default: `null`
1061
1062**Options**
1063
1064To override settings for a language, add an entry for that languages name to the `languages` value. Example:
1065
1066```json
1067"languages": {
1068 "C": {
1069 "format_on_save": "off",
1070 "preferred_line_length": 64,
1071 "soft_wrap": "preferred_line_length"
1072 },
1073 "JSON": {
1074 "tab_size": 4
1075 }
1076}
1077```
1078
1079The following settings can be overridden for each specific language:
1080
1081- `enable_language_server`
1082- `ensure_final_newline_on_save`
1083- `format_on_save`
1084- `formatter`
1085- `hard_tabs`
1086- `preferred_line_length`
1087- `remove_trailing_whitespace_on_save`
1088- `show_inline_completions`
1089- `show_whitespaces`
1090- `soft_wrap`
1091- `tab_size`
1092- `use_autoclose`
1093- `always_treat_brackets_as_autoclosed`
1094
1095These values take in the same options as the root-level settings with the same name.
1096
1097## Network Proxy
1098
1099- Description: Configure a network proxy for Zed.
1100- Setting: `proxy`
1101- Default: `null`
1102
1103**Options**
1104
1105The proxy setting must contain a URL to the proxy.
1106
1107The following URI schemes are supported:
1108
1109- `http`
1110- `https`
1111- `socks4`
1112- `socks4a`
1113- `socks5`
1114- `socks5h`
1115
1116`http` will be used when no scheme is specified.
1117
1118By 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`.
1119
1120For example, to set an `http` proxy, add the following to your settings:
1121
1122```json
1123{
1124 "proxy": "http://127.0.0.1:10809"
1125}
1126```
1127
1128Or to set a `socks5` proxy:
1129
1130```json
1131{
1132 "proxy": "socks5://localhost:10808"
1133}
1134```
1135
1136## Preview tabs
1137
1138- Description:
1139 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. \
1140 There are several ways to convert a preview tab into a regular tab:
1141
1142 - Double-clicking on the file
1143 - Double-clicking on the tab header
1144 - Using the `project_panel::OpenPermanent` action
1145 - Editing the file
1146 - Dragging the file to a different pane
1147
1148- Setting: `preview_tabs`
1149- Default:
1150
1151```json
1152"preview_tabs": {
1153 "enabled": true,
1154 "enable_preview_from_file_finder": false,
1155 "enable_preview_from_code_navigation": false,
1156}
1157```
1158
1159### Enable preview from file finder
1160
1161- Description: Determines whether to open files in preview mode when selected from the file finder.
1162- Setting: `enable_preview_from_file_finder`
1163- Default: `false`
1164
1165**Options**
1166
1167`boolean` values
1168
1169### Enable preview from code navigation
1170
1171- Description: Determines whether a preview tab gets replaced when code navigation is used to navigate away from the tab.
1172- Setting: `enable_preview_from_code_navigation`
1173- Default: `false`
1174
1175**Options**
1176
1177`boolean` values
1178
1179## Preferred Line Length
1180
1181- Description: The column at which to soft-wrap lines, for buffers where soft-wrap is enabled.
1182- Setting: `preferred_line_length`
1183- Default: `80`
1184
1185**Options**
1186
1187`integer` values
1188
1189## Projects Online By Default
1190
1191- Description: Whether or not to show the online projects view by default.
1192- Setting: `projects_online_by_default`
1193- Default: `true`
1194
1195**Options**
1196
1197`boolean` values
1198
1199## Remove Trailing Whitespace On Save
1200
1201- Description: Whether or not to remove any trailing whitespace from lines of a buffer before saving it.
1202- Setting: `remove_trailing_whitespace_on_save`
1203- Default: `true`
1204
1205**Options**
1206
1207`boolean` values
1208
1209## Search
1210
1211- Description: Search options to enable by default when opening new project and buffer searches.
1212- Setting: `search`
1213- Default:
1214
1215```json
1216"search": {
1217 "whole_word": false,
1218 "case_sensitive": false,
1219 "include_ignored": false,
1220 "regex": false
1221},
1222```
1223
1224## Show Call Status Icon
1225
1226- Description: Whether or not to show the call status icon in the status bar.
1227- Setting: `show_call_status_icon`
1228- Default: `true`
1229
1230**Options**
1231
1232`boolean` values
1233
1234## Show Completions On Input
1235
1236- Description: Whether or not to show completions as you type.
1237- Setting: `show_completions_on_input`
1238- Default: `true`
1239
1240**Options**
1241
1242`boolean` values
1243
1244## Show Completion Documentation
1245
1246- Description: Whether to display inline and alongside documentation for items in the completions menu.
1247- Setting: `show_completion_documentation`
1248- Default: `true`
1249
1250**Options**
1251
1252`boolean` values
1253
1254## Completion Documentation Debounce Delay
1255
1256- Description: The debounce delay before re-querying the language server for completion documentation when not included in original completion list.
1257- Setting: `completion_documentation_secondary_query_debounce`
1258- Default: `300` ms
1259
1260**Options**
1261
1262`integer` values
1263
1264## Show Inline Completions
1265
1266- Description: Whether to show inline completions as you type or manually by triggering `editor::ShowInlineCompletion`.
1267- Setting: `show_inline_completions`
1268- Default: `true`
1269
1270**Options**
1271
1272`boolean` values
1273
1274## Show Whitespaces
1275
1276- Description: Whether or not to show render whitespace characters in the editor.
1277- Setting: `show_whitespaces`
1278- Default: `selection`
1279
1280**Options**
1281
12821. `all`
12832. `selection`
12843. `none`
12854. `boundary`
1286
1287## Soft Wrap
1288
1289- Description: Whether or not to automatically wrap lines of text to fit editor / preferred width.
1290- Setting: `soft_wrap`
1291- Default: `prefer_line`
1292
1293**Options**
1294
12951. `none` to stop the soft-wrapping
12962. `prefer_line` to avoid wrapping generally, unless the line is too long
12973. `editor_width` to wrap lines that overflow the editor width
12984. `preferred_line_length` to wrap lines that overflow `preferred_line_length` config value
1299
1300## Wrap Guides (Vertical Rulers)
1301
1302- Description: Where to display vertical rulers as wrap-guides. Disable by setting `show_wrap_guides` to `false`.
1303- Setting: `wrap_guides`
1304- Default: []
1305
1306**Options**
1307
1308List of `integer` column numbers
1309
1310## Tab Size
1311
1312- Description: The number of spaces to use for each tab character.
1313- Setting: `tab_size`
1314- Default: `4`
1315
1316**Options**
1317
1318`integer` values
1319
1320## Telemetry
1321
1322- Description: Control what info is collected by Zed.
1323- Setting: `telemetry`
1324- Default:
1325
1326```json
1327"telemetry": {
1328 "diagnostics": true,
1329 "metrics": true
1330},
1331```
1332
1333**Options**
1334
1335### Diagnostics
1336
1337- Description: Setting for sending debug-related data, such as crash reports.
1338- Setting: `diagnostics`
1339- Default: `true`
1340
1341**Options**
1342
1343`boolean` values
1344
1345### Metrics
1346
1347- Description: Setting for sending anonymized usage data, such what languages you're using Zed with.
1348- Setting: `metrics`
1349- Default: `true`
1350
1351**Options**
1352
1353`boolean` values
1354
1355## Terminal
1356
1357- Description: Configuration for the terminal.
1358- Setting: `terminal`
1359- Default:
1360
1361```json
1362{
1363 "terminal": {
1364 "alternate_scroll": "off",
1365 "blinking": "terminal_controlled",
1366 "copy_on_select": false,
1367 "dock": "bottom",
1368 "detect_venv": {
1369 "on": {
1370 "directories": [".env", "env", ".venv", "venv"],
1371 "activate_script": "default"
1372 }
1373 }
1374 "env": {},
1375 "font_family": null,
1376 "font_features": null,
1377 "font_size": null,
1378 "line_height": "comfortable",
1379 "option_as_meta": true,
1380 "button": false,
1381 "shell": {},
1382 "toolbar": {
1383 "title": true
1384 },
1385 "working_directory": "current_project_directory"
1386 }
1387}
1388```
1389
1390### Terminal: Dock
1391
1392- Description: Control the position of the dock
1393- Setting: `dock`
1394- Default: `bottom`
1395
1396**Options**
1397
1398`"bottom"`, `"left"` or `"right"`
1399
1400### Terminal: Alternate Scroll
1401
1402- 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.
1403- Setting: `alternate_scroll`
1404- Default: `off`
1405
1406**Options**
1407
14081. Default alternate scroll mode to on
1409
1410```json
1411{
1412 "terminal": {
1413 "alternate_scroll": "on"
1414 }
1415}
1416```
1417
14182. Default alternate scroll mode to off
1419
1420```json
1421{
1422 "terminal": {
1423 "alternate_scroll": "off"
1424 }
1425}
1426```
1427
1428### Terminal: Blinking
1429
1430- Description: Set the cursor blinking behavior in the terminal
1431- Setting: `blinking`
1432- Default: `terminal_controlled`
1433
1434**Options**
1435
14361. Never blink the cursor, ignore the terminal mode
1437
1438```json
1439{
1440 "terminal": {
1441 "blinking": "off"
1442 }
1443}
1444```
1445
14462. Default the cursor blink to off, but allow the terminal to turn blinking on
1447
1448```json
1449{
1450 "terminal": {
1451 "blinking": "terminal_controlled"
1452 }
1453}
1454```
1455
14563. Always blink the cursor, ignore the terminal mode
1457
1458```json
1459{
1460 "terminal": {
1461 "blinking": "on"
1462 }
1463}
1464```
1465
1466### Terminal: Copy On Select
1467
1468- Description: Whether or not selecting text in the terminal will automatically copy to the system clipboard.
1469- Setting: `copy_on_select`
1470- Default: `false`
1471
1472**Options**
1473
1474`boolean` values
1475
1476**Example**
1477
1478```json
1479{
1480 "terminal": {
1481 "copy_on_select": true
1482 }
1483}
1484```
1485
1486### Terminal: Env
1487
1488- 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
1489- Setting: `env`
1490- Default: `{}`
1491
1492**Example**
1493
1494```json
1495{
1496 "terminal": {
1497 "env": {
1498 "ZED": "1",
1499 "KEY": "value1:value2"
1500 }
1501 }
1502}
1503```
1504
1505### Terminal: Font Size
1506
1507- Description: What font size to use for the terminal. When not set defaults to matching the editor's font size
1508- Setting: `font_size`
1509- Default: `null`
1510
1511**Options**
1512
1513`integer` values
1514
1515```json
1516{
1517 "terminal": {
1518 "font_size": 15
1519 }
1520}
1521```
1522
1523### Terminal: Font Family
1524
1525- Description: What font to use for the terminal. When not set, defaults to matching the editor's font.
1526- Setting: `font_family`
1527- Default: `null`
1528
1529**Options**
1530
1531The name of any font family installed on the user's system
1532
1533```json
1534{
1535 "terminal": {
1536 "font_family": "Berkeley Mono"
1537 }
1538}
1539```
1540
1541### Terminal: Font Features
1542
1543- Description: What font features to use for the terminal. When not set, defaults to matching the editor's font features.
1544- Setting: `font_features`
1545- Default: `null`
1546- Platform: macOS and Windows.
1547
1548**Options**
1549
1550See Buffer Font Features
1551
1552```json
1553{
1554 "terminal": {
1555 "font_features": {
1556 "calt": false
1557 // See Buffer Font Features for more features
1558 }
1559 }
1560}
1561```
1562
1563### Terminal: Line Height
1564
1565- Description: Set the terminal's line height.
1566- Setting: `line_height`
1567- Default: `comfortable`
1568
1569**Options**
1570
15711. Use a line height that's `comfortable` for reading, 1.618. (default)
1572
1573```json
1574{
1575 "terminal": {
1576 "line_height": "comfortable"
1577 }
1578}
1579```
1580
15812. Use a `standard` line height, 1.3. This option is useful for TUIs, particularly if they use box characters
1582
1583```json
1584{
1585 "terminal": {
1586 "line_height": "standard"
1587 }
1588}
1589```
1590
15913. Use a custom line height.
1592
1593```json
1594{
1595 "terminal": {
1596 "line_height": {
1597 "custom": 2
1598 }
1599 }
1600}
1601```
1602
1603### Terminal: Option As Meta
1604
1605- Description: Re-interprets the option keys to act like a 'meta' key, like in Emacs.
1606- Setting: `option_as_meta`
1607- Default: `true`
1608
1609**Options**
1610
1611`boolean` values
1612
1613```json
1614{
1615 "terminal": {
1616 "option_as_meta": true
1617 }
1618}
1619```
1620
1621### Terminal: Shell
1622
1623- Description: What shell to use when launching the terminal.
1624- Setting: `shell`
1625- Default: `system`
1626
1627**Options**
1628
16291. Use the system's default terminal configuration (usually the `/etc/passwd` file).
1630
1631```json
1632{
1633 "terminal": {
1634 "shell": "system"
1635 }
1636}
1637```
1638
16392. A program to launch:
1640
1641```json
1642{
1643 "terminal": {
1644 "shell": {
1645 "program": "sh"
1646 }
1647 }
1648}
1649```
1650
16513. A program with arguments:
1652
1653```json
1654{
1655 "terminal": {
1656 "shell": {
1657 "with_arguments": {
1658 "program": "/bin/bash",
1659 "args": ["--login"]
1660 }
1661 }
1662 }
1663}
1664```
1665
1666## Terminal: Detect Virtual Environments {#terminal-detect_venv}
1667
1668- 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
1669- Setting: `detect_venv`
1670- Default:
1671
1672```json
1673{
1674 "terminal":
1675 "detect_venv": {
1676 "on": {
1677 // Default directories to search for virtual environments, relative
1678 // to the current working directory. We recommend overriding this
1679 // in your project's settings, rather than globally.
1680 "directories": [".venv", "venv"],
1681 // Can also be `csh`, `fish`, and `nushell`
1682 "activate_script": "default"
1683 }
1684 }
1685 }
1686}
1687```
1688
1689Disable with:
1690
1691```json
1692{
1693 "terminal":
1694 "detect_venv": "off"
1695 }
1696}
1697```
1698
1699## Terminal: Toolbar
1700
1701- Description: Whether or not to show various elements in the terminal toolbar. It only affects terminals placed in the editor pane.
1702- Setting: `toolbar`
1703- Default:
1704
1705```json
1706{
1707 "terminal": {
1708 "toolbar": {
1709 "title": true
1710 }
1711 }
1712}
1713```
1714
1715**Options**
1716
1717At 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.
1718
1719### Terminal: Button
1720
1721- Description: Control to show or hide the terminal button in the status bar
1722- Setting: `button`
1723- Default: `true`
1724
1725**Options**
1726
1727`boolean` values
1728
1729```json
1730{
1731 "terminal": {
1732 "button": false
1733 }
1734}
1735```
1736
1737### Terminal: Working Directory
1738
1739- Description: What working directory to use when launching the terminal.
1740- Setting: `working_directory`
1741- Default: `"current_project_directory"`
1742
1743**Options**
1744
17451. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful
1746
1747```json
1748{
1749 "terminal": {
1750 "working_directory": "current_project_directory"
1751 }
1752}
1753```
1754
17552. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.
1756
1757```json
1758{
1759 "terminal": {
1760 "working_directory": "first_project_directory"
1761 }
1762}
1763```
1764
17653. Always use this platform's home directory (if we can find it)
1766
1767```json
1768{
1769 "terminal": {
1770 "working_directory": "always_home"
1771 }
1772}
1773```
1774
17754. 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.
1776
1777```json
1778{
1779 "terminal": {
1780 "working_directory": {
1781 "always": {
1782 "directory": "~/zed/projects/"
1783 }
1784 }
1785 }
1786}
1787```
1788
1789## Theme
1790
1791- 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.
1792- Setting: `theme`
1793- Default: `One Dark`
1794
1795### Theme Object
1796
1797- Description: Specify the theme using an object that includes the `mode`, `dark`, and `light` themes.
1798- Setting: `theme`
1799- Default:
1800
1801```json
1802"theme": {
1803 "mode": "system",
1804 "dark": "One Dark",
1805 "light": "One Light"
1806},
1807```
1808
1809### Mode
1810
1811- Description: Specify theme mode.
1812- Setting: `mode`
1813- Default: `system`
1814
1815**Options**
1816
18171. Set the theme to dark mode
1818
1819```json
1820{
1821 "mode": "dark"
1822}
1823```
1824
18252. Set the theme to light mode
1826
1827```json
1828{
1829 "mode": "light"
1830}
1831```
1832
18333. Set the theme to system mode
1834
1835```json
1836{
1837 "mode": "system"
1838}
1839```
1840
1841### Dark
1842
1843- Description: The name of the dark Zed theme to use for the UI.
1844- Setting: `dark`
1845- Default: `One Dark`
1846
1847**Options**
1848
1849Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1850
1851### Light
1852
1853- Description: The name of the light Zed theme to use for the UI.
1854- Setting: `light`
1855- Default: `One Light`
1856
1857**Options**
1858
1859Run the `theme selector: toggle` action in the command palette to see a current list of valid themes names.
1860
1861## Vim
1862
1863- Description: Whether or not to enable vim mode (work in progress).
1864- Setting: `vim_mode`
1865- Default: `false`
1866
1867## Project Panel
1868
1869- Description: Customize project panel
1870- Setting: `project_panel`
1871- Default:
1872
1873```json
1874{
1875 "project_panel": {
1876 "button": true,
1877 "default_width": 240,
1878 "dock": "left",
1879 "file_icons": true,
1880 "folder_icons": true,
1881 "git_status": true,
1882 "indent_size": 20,
1883 "auto_reveal_entries": true,
1884 "auto_fold_dirs": true,
1885 "scrollbar": {
1886 "show": "always"
1887 }
1888 }
1889}
1890```
1891
1892### Dock
1893
1894- Description: Control the position of the dock
1895- Setting: `dock`
1896- Default: `left`
1897
1898**Options**
1899
19001. Default dock position to left
1901
1902```json
1903{
1904 "dock": "left"
1905}
1906```
1907
19082. Default dock position to right
1909
1910```json
1911{
1912 "dock": "right"
1913}
1914```
1915
1916### Git Status
1917
1918- Description: Indicates newly created and updated files
1919- Setting: `git_status`
1920- Default: `true`
1921
1922**Options**
1923
19241. Default enable git status
1925
1926```json
1927{
1928 "git_status": true
1929}
1930```
1931
19322. Default disable git status
1933
1934```json
1935{
1936 "git_status": false
1937}
1938```
1939
1940### Default Width
1941
1942- Description: Customize default width taken by project panel
1943- Setting: `default_width`
1944- Default: N/A width in pixels (eg: 420)
1945
1946**Options**
1947
1948`boolean` values
1949
1950### Auto Reveal Entries
1951
1952- Description: Whether to reveal it in the project panel automatically, when a corresponding project entry becomes active. Gitignored entries are never auto revealed.
1953- Setting: `auto_reveal_entries`
1954- Default: `true`
1955
1956**Options**
1957
19581. Enable auto reveal entries
1959
1960```json
1961{
1962 "auto_reveal_entries": true
1963}
1964```
1965
19662. Disable auto reveal entries
1967
1968```json
1969{
1970 "auto_reveal_entries": false
1971}
1972```
1973
1974### Auto Fold Dirs
1975
1976- Description: Whether to fold directories automatically when directory has only one directory inside.
1977- Setting: `auto_fold_dirs`
1978- Default: `true`
1979
1980**Options**
1981
19821. Enable auto fold dirs
1983
1984```json
1985{
1986 "auto_fold_dirs": true
1987}
1988```
1989
19902. Disable auto fold dirs
1991
1992```json
1993{
1994 "auto_fold_dirs": false
1995}
1996```
1997
1998### Indent Size
1999
2000- Description: Amount of indentation (in pixels) for nested items.
2001- Setting: `indent_size`
2002- Default: `20`
2003
2004### Scrollbar
2005
2006- Description: Scrollbar related settings. Possible values: "always", "never".
2007- Setting: `scrollbar`
2008- Default:
2009
2010```json
2011"scrollbar": {
2012 "show": "always"
2013}
2014```
2015
2016**Options**
2017
20181. Show scrollbar in project panel
2019
2020```json
2021{
2022 "scrollbar": {
2023 "show": "always"
2024 }
2025}
2026```
2027
20282. Hide scrollbar in project panel
2029
2030```json
2031{
2032 "scrollbar": {
2033 "show": "never"
2034 }
2035}
2036```
2037
2038## Assistant Panel
2039
2040- Description: Customize assistant panel
2041- Setting: `assistant`
2042- Default:
2043
2044```json
2045"assistant": {
2046 "enabled": true,
2047 "button": true,
2048 "dock": "right",
2049 "default_width": 640,
2050 "default_height": 320,
2051 "provider": "openai",
2052 "version": "1",
2053},
2054```
2055
2056## Outline Panel
2057
2058- Description: Customize outline Panel
2059- Setting: `outline_panel`
2060- Default:
2061
2062```json
2063"outline_panel": {
2064 "button": true,
2065 "default_width": 240,
2066 "dock": "left",
2067 "file_icons": true,
2068 "folder_icons": true,
2069 "git_status": true,
2070 "indent_size": 20,
2071 "auto_reveal_entries": true,
2072 "auto_fold_dirs": true,
2073}
2074```
2075
2076## Calls
2077
2078- Description: Customize behavior when participating in a call
2079- Setting: `calls`
2080- Default:
2081
2082```json
2083"calls": {
2084 // Join calls with the microphone live by default
2085 "mute_on_join": false,
2086 // Share your project when you are the first to join a channel
2087 "share_on_join": false
2088},
2089```
2090
2091## Unnecessary Code Fade
2092
2093- Description: How much to fade out unused code.
2094- Setting: `unnecessary_code_fade`
2095- Default: `0.3`
2096
2097**Options**
2098
2099Float values between `0.0` and `0.9`, where:
2100
2101- `0.0` means no fading (unused code looks the same as used code)
2102- `0.9` means maximum fading (unused code is very faint but still visible)
2103
2104**Example**
2105
2106```json
2107{
2108 "unnecessary_code_fade": 0.5
2109}
2110```
2111
2112## An example configuration:
2113
2114```json
2115// ~/.config/zed/settings.json
2116{
2117 "theme": "cave-light",
2118 "tab_size": 2,
2119 "preferred_line_length": 80,
2120 "soft_wrap": "none",
2121
2122 "buffer_font_size": 18,
2123 "buffer_font_family": "Zed Plex Mono",
2124
2125 "autosave": "on_focus_change",
2126 "format_on_save": "off",
2127 "vim_mode": false,
2128 "projects_online_by_default": true,
2129 "terminal": {
2130 "font_family": "FiraCode Nerd Font Mono",
2131 "blinking": "off"
2132 },
2133 "languages": {
2134 "C": {
2135 "format_on_save": "language_server",
2136 "preferred_line_length": 64,
2137 "soft_wrap": "preferred_line_length"
2138 }
2139 }
2140}
2141```