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

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

Per-build Configuration Options

The following options can be set on a per-project basis by placing zls.build.json in the project root directory next to build.zig.

Option	Type	Default value	What it Does
relative_builtin_path	?[]const u8	null	If present, this path is used to resolve @import("builtin")
build_options	?[]BuildOption	null	If present, this contains a list of user options to pass to the build. This is useful when options are used to conditionally add packages in build.zig.

BuildOption

BuildOption is defined as follows:

const BuildOption = struct {
    name: []const u8,
    value: ?[]const u8 = null,
};

When value is present, the option will be passed the same as in zig build -Dname=value. When value is null, the option will be passed as a flag instead as in zig build -Dflag.