Configuration

Important

ZLS works perfectly without any configuration since all options have reasonable defaults. Feel free to read through the available config options but unless there is something you want to change, there is no need to configure ZLS.

Please go through the Installation Guide first before configuring ZLS.

In-Editor Configuration (recommended)

In-Editor Config (or Workspace Config) will integrate with the config system of you editor to also configure ZLS.

This feature is available for the following editors:

• VS Code
• Sublime Text 4
• Helix
• Neovim with nvim-lspconfig

This is allows you to configure ZLS on a per-editor basis. Some editors (like VS Code) also allow workspace-specific configuration. If you want to share the same configuration across multiple editors, please refer to the zls.json alternative.

zls.json

You can configure ZLS by creating a zls.json configuration file. This config will apply to all editors that use ZLS.

Here is an example:

{
  "zig_exe_path": "/path/to/zig_executable",
  "semantic_tokens": "partial",
  "enable_build_on_save": true
}

The file must be valid JSON which cannot contain comments or trailing commas.

Available Configuration Options

You can find all available config options by looking at src/Config.zig or the JSON Schema.

Where should the zls.json be created?

ZLS since #1957

Running zls env will show you where ZLS will look for the zls.json file:

{
 "version": "0.14.0-dev.46+efed0c93",
 "global_cache_dir": "/home/anon/.cache/zls",
 "global_config_dir": "/etc/xdg",
 "local_config_dir": "/home/anon/.config",
 "config_file": null,
 "log_file": "/home/anon/.cache/zls/zls.log"
}

ZLS will look for a zls.json in the local_config_dir directory and then fallback to global_config_dir.

After creating the configuration file at $local_config_dir/zls.json, zls env should output the following:

{
 "version": "0.14.0-dev.46+efed0c93",
 "global_cache_dir": "/home/anon/.cache/zls",
 "global_config_dir": "/etc/xdg",
 "local_config_dir": "/home/anon/.config",
 "config_file": "/home/anon/.config/zls.json",
 "log_file": "/home/anon/.cache/zls/zls.log"
}

ZLS before #1957

Running zls --show-config-path will show a path to an already existing zls.json or a path to the local configuration folder instead.

> zls --show-config-path
info  ( main ): No config file zls.json found.
info  ( main ): A path to the local configuration folder will be printed instead.
/home/anon/.config/zls.json