zls.json Config

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 of how a zls.json could look like:

{
  "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.

Where should the zls.json be created?

ZLS since 0.14.0-dev.50+3354fdcb

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

{
  "version": "0.14.0-dev.50+3354fdcb",
  "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.50+3354fdcb",
  "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 0.14.0-dev.50+3354fdcb (like ZLS 0.13.0)

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

JSON Schema

ZLS provides a JSON Schema to validate the configuration file. It can be used to validate the configuration file and provide IntelliSense features to editors. Further information about JSON Schemas can be found at https://json-schema.org.

You can add a mapping to zls.json that can be used by some editors:

{
  "$schema": "https://raw.githubusercontent.com/zigtools/zls/refs/heads/master/schema.json",
  "zig_exe_path": "/path/to/zig_executable",
  "semantic_tokens": "partial",
  "enable_build_on_save": true
}

Please refer to your Editor’s Documentation to find out if and how they support JSON Schemas.

Be aware that configuration options change over time. The example above assumes that you are using ZLS nightly/master. If you use a tagged release of ZLS, you will need to the JSON Schema of the respective version: https://raw.githubusercontent.com/zigtools/zls/refs/tags/<ZLS_VERSION_HERE>/schema.json.