Installation

Install ZLS

Note

Visual Studio Code users do not need to install Zig or ZLS manually and can continue here.

Warning

A tagged release of ZLS is only compatible with the same tagged release of Zig.

A nightly/master build of ZLS is only compatible with nightly/master Zig. Do not use it with a tagged release of Zig and always update Zig and ZLS together.

Prebuilt Binaries

Tip

It is recommended to add Zig to your PATH before installing ZLS.

Latest nightly

Note

LINUX: The zls file is not executable by default, but that is needed to be functional. Run chmod +x zls to make zls executable.

	x86-64	x86	AArch64
Linux	x86-64 Linux	x86 Linux	AArch64 Linux
Windows	x86-64 Windows	x86 Windows	-
MacOS	x86 MacOS	-	AArch64 Macos

A JSON Index of all recent ZLS versions is also available.

Release

Head to the Releases tab and select the right executable in the Assets section at the bottom of the latest release.

tar -x --strip-components=1 -f [archive] [output_path]

From Source

Important

The master branch cannot be build with a tagged release of Zig.

Use git checkout $TAGGED_VERSION (example: git checkout 0.11.0) to checkout a tagged release of ZLS.

Building ZLS requires a build of Zig master.

git clone https://github.com/zigtools/zls
cd zls
zig build -Doptimize=ReleaseSafe

Install Editor Extension

Tip

Many editor extensions can find Zig and ZLS automatically by adding them to your PATH.

Visual Studio Code

Using ZLS in Visual Studio Code is as simple as installing the official Zig Language extension (open in VSCode).

Sublime Text

1. install the LSP and sublime-zig-language package (Package Control Usage)
2. place the following snippet in the LSP.sublime-settings (Preferences -> Package Settings -> LSP -> Settings)
3. place the following snippet in the Zig.sublime-settings (Preferences -> Package Settings -> Zig -> Settings)

show Zig.sublime-settings

// Zig.sublime-settings
{
    // ZLS will run format on save
    "zig.fmt.on_save": false,
    // automatically hide the build/fmt output panel 
    "zig.quiet": true,
}

Sublime Text 4

show LSP.sublime-settings

// LSP.sublime-settings
{
    // General settings
    // Keep in mind that these settings apply to any language and not just Zig.

    // ZLS uses `zig fmt` as the formatter.
    // The Zig FAQ answers some questions about `zig fmt`:
    // https://github.com/ziglang/zig/wiki/FAQ
    "lsp_format_on_save": true,
    "lsp_code_actions_on_save": {
      // Enable code actions that currently supports adding and removing discards.
      "source.fixAll": true,
    },
    // Show inlay hints in the editor. Inlay hints are short annotations within the code,
    // which show variable types or parameter names.
    "show_inlay_hints": true,
    "semantic_highlighting": true,

    "clients": {
        "zig": {
            // Enable or disable this client configuration.
            "enabled": true,
            // The command line required to run the server.
            "command": ["/path/to/zls_executable"],
            "selector": "source.zig",
            // There are two ways to set config options:
            //   - edit your `zls.json` that applies to any editor that uses ZLS
            //   - set in-editor config options with the `settings` field below.
            //
            // Further information on how to configure ZLS:
            // https://github.com/zigtools/zls/wiki/Configuration
            "settings": {
                // Whether to enable build-on-save diagnostics
                // "enable_build_on_save": true,

                // omit the following line if `zig` is in your PATH
                "zig_exe_path": "/path/to/zig_executable"
            }
        }
    }
}

Sublime Text 3

show LSP.sublime-settings

// LSP.sublime-settings
{
    "clients": {
        "zig": {
            "command": ["/path/to/zls_executable"],
            "enabled": true,
            "languageId": "zig",
            "scopes": ["source.zig"],
            "syntaxes": ["Packages/Zig Language/Syntaxes/Zig.tmLanguage"]
        }
    }
}

CLion / other JetBrains IDEs

• Install the ZigBrains plugin from the marketplace
• Restart the IDE (necessary for the plugin to integrate itself correctly)

If you have both zig and zls on $PATH, then the plugin should automatically detect both.

If not, Go to Settings -> Languages & Frameworks -> Zig, and point the Toolchain Location and ZLS path to the zig compiler's directory and the ZLS executable, respectively.

If everything is set up correctly, an LSP status indicator should appear in the bottom right corner and turn to green when you open a .zig file in the editor.

Helix

If zls and zig are in your PATH, everything should work out of the box.

To apply in-editor configuration or manually specify paths to zls or zig, open <config_dir>/helix/languages.toml and add the following:

show languages.toml

[language-server.zls]
# omit the following line if `zls` is in your PATH
command = "/path/to/zls_executable"
# There are two ways to set config options:
#   - edit your `zls.json` that applies to any editor that uses ZLS
#   - set in-editor config options with the `config.<name>` fields below.
#
# Further information on how to configure ZLS:
# https://github.com/zigtools/zls/wiki/Configuration

# Whether to enable build-on-save diagnostics
# config.enable_build_on_save = true
# omit the following line if `zig` is in your PATH
config.zig_exe_path = "/path/to/zig_executable"

Further information on languages.toml files

To make sure that Zig and ZLS are set up as expected you should run the Helix health check:

hx --health zig

For more information on the health check results refer to Health check.

Neovim / Vim8

Warning

The mason package manager can only install the latest tagged release of ZLS which should not be used with Zig master. Do not use ZLS from mason with Zig master.

nvim-lspconfig

The following two configs only contain the necessary ZLS specific configuration. Please refer to nvim-lspconfig on how to setup everything else like keybindings or autocompletion.

Install vim-plug plugin manager from here.

init.lua with vim-plug

show config

local vim = vim
local Plug = vim.fn['plug#']

vim.call('plug#begin')
Plug('neovim/nvim-lspconfig') -- https://github.com/neovim/nvim-lspconfig
Plug('ziglang/zig.vim') -- https://github.com/ziglang/zig.vim
vim.call('plug#end')

local lspconfig = require('lspconfig')
lspconfig.zls.setup {
  -- Server-specific settings. See `:help lspconfig-setup`

  -- omit the following line if `zls` is in your PATH
  cmd = { '/path/to/zls_executable' },
  -- There are two ways to set config options:
  --   - edit your `zls.json` that applies to any editor that uses ZLS
  --   - set in-editor config options with the `settings` field below.
  --
  -- Further information on how to configure ZLS:
  -- https://github.com/zigtools/zls/wiki/Configuration
  settings = {
    zls = {
      -- omit the following line if `zig` is in your PATH
      zig_exe_path = '/path/to/zig_executable',
    }
  }
}

init.vim with vim-plug

show config

call plug#begin('~/.config/nvim/plugged')
Plug 'neovim/nvim-lspconfig' " https://github.com/neovim/nvim-lspconfig
Plug 'ziglang/zig.vim' " https://github.com/ziglang/zig.vim
call plug#end()

:lua << EOF
  local lspconfig = require('lspconfig')
  lspconfig.zls.setup {
    -- Server-specific settings. See `:help lspconfig-setup`

    -- omit the following line if `zls` is in your PATH
    cmd = { '/path/to/zls_executable' },
    -- There are two ways to set config options:
    --   - edit your `zls.json` that applies to any editor that uses ZLS
    --   - set in-editor config options with the `settings` field below.
    --
    -- Further information on how to configure ZLS:
    -- https://github.com/zigtools/zls/wiki/Configuration
    settings = {
      zls = {
        -- omit the following line if `zig` is in your PATH
        zig_exe_path = '/path/to/zig_executable',
      }
    }
  }
EOF

CoC

With Extension

Run :CocInstall coc-zls to install coc-zls. This extension supports the same functionality as the VS Code extension.

Manually

{
    "languageserver": {
        "zls" : {
            "command": "/path/to/zls_executable",
            "filetypes": ["zig"]
        }
    }
}

YouCompleteMe

• Install YouCompleteMe from here.
• Add these lines to your vimrc:

"ensure zig is a recognized filetype
autocmd BufNewFile,BufRead *.zig set filetype=zig
let g:ycm_language_server =
    \\ [
    \\{
    \\     'name': 'zls',
    \\     'filetypes': [ 'zig' ],
    \\     'cmdline': [ '/path/to/zls_executable' ]
    \\    }
    \\ ]

LanguageClient-neovim

• Install the LanguageClient-neovim from here.
• Edit your neovim configuration and add zls for zig filetypes:

let g:LanguageClient_serverCommands = {
        \\ 'zig': ['/path/to/zls_executable'],
        \\ }

Emacs

• Use the inbuilt eglot mode. Make sure Zls is in your path.
• zig mode is also useful.

Use M-x eglot in a zig-mode buffer to start the server.

Doom Emacs

• Enable :tools lsp module.
• Enable :lang (zig +lsp) module.
• Run doom sync in a terminal.

Spacemacs

• Add lsp and zig to dotspacemacs-configuration-layers in your .spacemacs file.
• If you don't have zls in your PATH, add the following to dotspacemacs/user-config in your .spacemacs file:

(setq lsp-zig-zls-executable "/path/to/zls_executable")

Kate

Kate has builtin support for Zig and automatically asks you to enable ZLS if if is found in your $PATH.

You can enable some LSP related settings like "Inlay Hints" or "Format on Save" under Settings -> LSP Client -> Client Settings

If you wish to manually specify the path to the ZLS executable, open Settings -> LSP Client -> User Server Settings and add the following snippet:

{
    "servers": {
        "zig": {
            "command": ["/path/to/zls_executable"],
            "url": "https://github.com/zigtools/zls",
            "highlightingModeRegex": "^Zig$"
        }
    }
}