Configuring Zed

Zed can be configured via a simple JSON file located at ~/.config/zed/settings.json.

Opening your settings file

You can open ~/.config/zed/settings.json via cmd-,, the command palette, or the Zed > Open Settings application menu item.

This file contains a JSON object and should look like this:

{
  "theme": "rosé-pine",
  "buffer_font_family": "PragmataPro Liga",
  "buffer_font_size": 16
}

Add entries to a JSON object in this file and save it to configure Zed.

Available settings

Autosave

The autosave setting has four different modes:

1. To disable autosave, set it to "off"

   {
     "autosave": "off"
   }
   

2. To autosave when focus changes, use "on_focus_change":

   {
     "autosave": "on_focus_change"
   }
   

3. To autosave when the active window changes, use "on_window_change":

   {
     "autosave": "on_window_change"
   }
   

4. To autosave after an inactivity period, use "after_delay":

   {
     "autosave": {
       "after_delay": {
         "milliseconds": 1000
       }
     }
   }
   

Format On Save

The format_on_save setting controls if files are formatted before saving. There are two modes:

1. on, enables format on save obeying formatter setting:

   {
     "format_on_save": "on"
   }
   

2. off, disables format on save:

   {
     "format_on_save": "off"
   }
   

Formatter

The formatter setting dictates how a format is performed and has two different modes:

1. To use the current language server, use "language_server":

   {
     "formatter": "language_server"
   }
   

2. 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):

   {
     "formatter": {
       "external": {
         "command": "sed",
         "arguments": ["-e", "s/ *$//"]
       }
     }
   }
   

Lsp

The following settings can be overridden for specific language servers:

• initialization_options

To override settings for a language, add an entry for that language server's name to the lsp value. Example:

"lsp": {
  "rust-analyzer": {
    "initialization_options": {
      "checkOnSave": {
        "command": "clippy" // rust-analyzer.checkOnSave.command
      }
    }
  }
}

Overrides

The following settings can be overridden for specific languages:

• tab_size
• hard_tabs
• soft_wrap
• preferred_line_length
• format_on_save
• formatter
• enable_language_server

To override settings for a language, add an entry for that languages name to the language_overrides value. Example:

"language_overrides": {
  "C": {
    "format_on_save": "off",
    "preferred_line_length": 64,
    "soft_wrap": "preferred_line_length"
  },
  "JSON": {
    "tab_size": 4
  }
}

For a complete list of languages you can override settings for see Supported Languages.

Terminal

Terminal: Launch Shell

What shell to use when opening a terminal. May take 3 values:

1. Use the system's default terminal configuration (usually the pw file).

   "shell": "system"
   

2. A program to launch:

   "shell": {
     "program": "sh"
   }
   

3. A program with arguments:

   "shell": {
       "with_arguments": {
         "program": "/bin/bash",
         "arguments": ["--login"]
       }
   }
   

Terminal: Working Directory Strategy

There are four possible values:

1. Use the current file's project directory. Will Fallback to the first project directory strategy if unsuccessful

   "working_directory": "current_project_directory"
   

2. Use the first project in this workspace's directory. Will fallback to using this platform's home directory.

   "working_directory": "first_project_directory"
   

3. Always use this platform's home directory (if we can find it)

   "working_directory": "always_home"
   

4. 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.

   "working_directory": {
       "always": {
         "directory": "~/zed/projects/"
       }
     }
   

Terminal: Cursor Blink

Set the cursor blinking behavior in the terminal. May take 3 values:

1. Never blink the cursor, ignore the terminal mode

   "blinking": "off",
   

2. Default the cursor blink to off, but allow the terminal to turn blinking on

   "blinking": "terminal_controlled",
   

3. Always blink the cursor, ignore the terminal mode

   "blinking": "on",
   

Terminal: Alternate Scroll Mode

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. May take 2 values:

1. Default alternate scroll mode to on

   "alternate_scroll": "on",
   

2. Default alternate scroll mode to off

   "alternate_scroll": "off",
   

Terminal: Enviroment Variables

Any key-value pairs added to this object will be added to the terminal's enviroment. Keys must be unique, use : to seperate multiple values in a single variable:

"env": {
    "ZED": "1",
    "KEY": "value1:value2"
}

An example configuration:

// ~/.config/zed/settings.json
{
  "theme": "cave-light",
  "tab_size": 2,
  "preferred_line_length": 80,
  "soft_wrap": "none",

  "buffer_font_size": 18,
  "buffer_font_family": "Zed Mono",

  "autosave": "on_focus_change",
  "format_on_save": "off",
  "vim_mode": false,
  "projects_online_by_default": true,
  "terminal": {
    "font_family": "FiraCode Nerd Font Mono",
    "blinking": "off"
  },
  "language_overrides": {
    "C": {
      "format_on_save": "language_server",
      "preferred_line_length": 64,
      "soft_wrap": "preferred_line_length"
    }
  }
}