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

OptionDefaultDescription
autosaveoffSee 'autosave' section below
buffer_font_familyzed-monostring Either zed-mono or the name of an installed Font family
buffer_font_size16number The editor font size
enable_language_servertrueboolean Whether language servers should be used
lspnullSee 'lsp' section below
format_on_saveonSee 'format on save' section below
formatterlanguage_serverSee 'formatter' section below
hard_tabsfalseboolean Indent using tabs instead of spaces
hover_popover_enabledtrueboolean Enables triggering the hover popover with the mouse
show_completions_on_inputtrueboolean Causes the completion menu to show in editors while typing
language_overridesnullSee 'overrides' section below
tab_size4The number of columns occupied by a tab
themeone-darkstring The name of a Zed theme
preferred_line_length80The number of characters at which to soft wrap lines, when soft wrap is enabled
projects_online_by_defaulttrueboolean Project goes online when opened.
soft_wrapeditor_widtheditor_width, none, preferred_line_length
vim_modefalseboolean Enables Vim mode (WIP)
terminalSee belowSee 'Terminal' section below
experiments{}See the Experimental Features page

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

OptionDefaultDescription
shell"system"What shell to use on launch, see below
working_directory"current_project_directory"What working directory strategy to use, see below.
blinking"terminal_controlled"Set the terminal cursor blink, see below.
alternate_scroll"on"Default for the terminal alternate scroll mode, see below.
option_as_metatruere-interprets the option keys to act like a 'meta' key, like in emacs
env{}See below
font_sizenot setWhat font size to use for the terminal. When not set defaults to matching the editor's font size
font_familynot setWhat font to use for the terminal. When not set, defaults to matching the editor's font

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"
    }
  }
}