ZLS (Zig Language Server) - Stop Your Editor From Sucking at Zig

Writing Zig without autocomplete is fucking miserable, so that's why ZLS exists. I spent three months debugging phantom errors before I realized half were typos that any decent language server would've caught.

ZLS 0.15.0 dropped August 24, 2025, and only works with Zig 0.15.1 - not 0.15.0 because that was retracted for being broken. Version compatibility is stricter than a bank loan officer. The smart thing about ZLS is it uses LSP, so they only have to build one thing that works with every editor instead of writing VS Code extensions, Vim plugins, and Emacs modes separately.

How This Thing Actually Works

Your editor talks to ZLS through JSON-RPC messages - you type code, editor sends it to ZLS, ZLS analyzes it and sends back completions and errors. When ZLS gets better, every editor wins. Basic stuff.

The hard part is ZLS has to understand Zig's batshit crazy features like comptime where code runs at compile time. Spoiler alert: comptime analysis barely works. Try anything beyond const foo = @import(\"std\") and ZLS gives up. Don't expect rust-analyzer levels of intelligence here.

Setup ranges from "click install" (VS Code) to "sacrifice a goat and read three blog posts" (everything else).

Version Hell Will Ruin Your Day

This bears repeating: version mismatches will fuck your entire week. ZLS 0.15.0 works with Zig 0.15.1. Period. Mix versions and you get Segmentation fault (core dumped) with zero context about what went wrong.

I've been burned three times by this shit. Used ZLS 0.14 with Zig 0.15 and got segfaults that took two days to debug. The error message? "Unexpected token '}'" on a perfectly valid file. Thanks for nothing.

ZLS auto-detects your `build.zig` which works fine for hello world bullshit. Once you have actual dependencies or custom build steps, get ready for "unable to resolve symbol" errors on code that compiles just fine. At least ZLS 0.15.0 shows build errors inline now instead of making you tab over to the terminal every five minutes like a caveman.

What You Actually Get

ZLS has 4.1k stars which is decent for a language server that half the time makes you restart it. The zigtools org actually maintains this thing and ships updates regularly.

The basics work: autocomplete, go-to-definition, error squiggles. That's it. Comptime analysis is a joke - try any real metaprogramming and it gives up. Refactoring support makes rust-analyzer look like magic by comparison. But honestly? For normal Zig code it's the difference between "tolerable" and "wanting to switch back to C++."

Even TigerBeetle and Bun use it, so it can't be completely worthless.

LSP Features That Sometimes Work

ZLS 0.15.0 claims to support the usual LSP features. Here's what you'll actually get:

Shit that works most of the time:

• Autocomplete - Standard library stuff works, your own functions... maybe
• Go-to-definition - Works unless you have comptime, then good fucking luck
• Error squiggles - Real-time compiler errors (the one thing that actually works reliably)
• Formatting - zig fmt integration is solid, can't break that
• Find references - Basic symbol hunting works if ZLS isn't confused

Shit that works when Mercury is in retrograde:

• Hover info - Sometimes shows types, sometimes shows "unable to resolve"
• Comptime completions - Ha ha ha no. Maybe for @import("std")
• Symbol renaming - Can rename local variables. That's it. Don't get greedy.
• Workspace search - Finds symbols when your build config isn't fucked

What's Actually New in 0.15.0

The August 2025 release finally fixed some annoying shit:

Build Errors Show Up Inline:
ZLS now shows build.zig errors right in the editor instead of making you tab over to the terminal like a caveman. When your build script is borked, you'll know immediately instead of spending 10 minutes wondering why nothing compiles.

Unused Variables Don't Look Like Errors:
Unused vars get dimmed instead of showing red squiggles. Small win but I'll take it.

Syntax Highlighting Actually Makes Sense:
`var` vs `const` highlighting plus control flow highlighting that shows matching break/continue. Useful when you have nested loops that make your brain hurt.

Editor Setup War Stories

VS Code (The Only Sane Option):
Install the official extension, restart, done. This is the only setup that doesn't require googling error messages for three hours.

Neovim (For Masochists):
Modern configs usually have ZLS working. If you're building your own nvim config... Christ, just use the VS Code extension until your project is done.

Everything Else (Abandon Hope):
Installation guides exist but good luck. Emacs users: expect to edit init files. Sublime Text: hope you like JSON config files. JetBrains: their plugin system is a maze.

Nuclear option: ZLS stops working? Kill it and restart. Works 80% of the time. I don't know why this fixes most problems, but it does. Don't spend two hours debugging like I did - just restart the damn thing and move on with your life.

Build System Integration (AKA Dependency Hell)

ZLS auto-detects `build.zig` which works great until you have actual dependencies. Simple projects? Fine. The moment you add packages or custom build steps, ZLS gets confused and starts showing "unable to resolve" errors on perfectly valid code.

Real example: I had a project with a custom package path. ZLS couldn't find any symbols from that package. Spent four hours debugging, reading ZLS source code, checking my build.zig fifty times. Turns out ZLS doesn't handle relative paths in build.zig properly. The fix? Hardcode the absolute path. Fucking beautiful design right there.

Cross-compilation support exists but it's flaky. ZLS tries to match completions to your target but sometimes shows x86_64 symbols when you're targeting ARM. Close enough, I guess.

WebAssembly Support (Because Why Not)

ZLS compiles to WASM now because someone thought "let's make the slow language server even slower." The Zig Playground uses this for browser development. It works but holy shit is it slow.

Good for quick experiments when you can't install local tools. Bad for anything that requires performance. Like thinking.

Hard-learned lesson: Every time Zig releases a major version (every 6 months), ZLS breaks completely. Not "some features don't work" breaks - "segfaults on startup and ruins your entire day" breaks. I learned this the hard way during a deadline crunch. Budget a full day to upgrade and debug whatever compatibility nightmare they've cooked up this time.