# A language server for Lua, written in Lua

> MIT licensed, programmed in Lua, supporting Lua 5.1 through 5.5 plus LuaJIT, with 708 open issues and nearly a million Visual Studio Code installs. Telemetry was removed in 3.6.5 and the type checker is the hard part.

**LuaLS/lua-language-server** — A language server that offers Lua language support - programmed in Lua

- Repository: https://github.com/LuaLS/lua-language-server
- Website: https://luals.github.io
- Stars: 4,391 · Forks: 452
- Language: Lua
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/luals-lua-language-server

## Written in the language it serves

The GitHub description puts it plainly: a language server that offers Lua language support, programmed in Lua. That is unusual enough to be the first thing to note, and it has practical consequences. The server ships as a Lua program launched through a bundled interpreter, the tree contains `main.lua`, `make.lua`, `debugger.lua` and `test.lua` at the root, and the project uses LPeg and LPegLabel for parsing, which are Lua parser generator libraries rather than things you would reach for from C.

The scale of adoption is the other thing worth stating. The README claims nearly a million installs in Visual Studio Code and calls it the most popular extension for Lua language support, with badges for version, installs and downloads from the Visual Studio Marketplace under the publisher id `sumneko`. GitHub reports 4,371 stars, a last push on 2026-09-22, no archival, and 708 open issues.

An open issue count that size on a project this old and this central is a signal worth reading carefully rather than as neglect. The repository is MIT licensed with a `LICENSE` file, and topic tags include `language-server`, `lsp`, `lsp-server`, `lua`, `lpeg`, `lpeglabel` and `hacktoberfest`. Much of the issue volume comes from editor and platform variations rather than from the server itself, which is the usual profile for a language server.

The project's own site is luals.github.io, and the README points there for more information rather than trying to be the documentation. That is a reasonable division: the wiki carries the annotation and diagnostic reference, the README carries the feature list and installation surface.

## The feature list, and what each one actually costs you

The README enumerates the features compactly. Language support covers `Lua 5.5`, `Lua 5.4`, `Lua 5.3`, `Lua 5.2`, `Lua 5.1` and `LuaJIT`. There are over 20 supported annotations for documenting code. Then the standard language server operations: go to definition, find references, element renaming, and hover to view details on variables and functions, plus autocompletion.

Three entries in that list are where the project differs from a generic syntax server. Dynamic type checking is the headline: it infers types through your code rather than only reading annotations, and the README links it as a separate documentation page, which is the right signal that it has its own configuration surface. Diagnostics and warnings are listed separately from syntax checking, which reflects the same distinction: syntax checking is the parser complaining, diagnostics are the analyzer complaining about types, unused values and undefined fields.

Then the less common ones. Code formatting and spell checking are both listed, with spell checking documented under the diagnostics page. Documentation generation exports docs from your annotations. Custom plugins are supported and documented on their own wiki page. Library support is tied to a workspace setting, which is how a project declares the third-party Lua modules it uses so the server stops reporting them as undefined globals.

Spell checking inside a language server is an unusual choice and a good one for Lua specifically, because misspelled method names on tables are the most common class of silent bug in a dynamically typed language.

## Install paths: VS Code, Neovim, or anything speaking LSP

The README is direct about the three supported routes. The language server can be installed for use in Visual Studio Code, NeoVim, and any other client that supports the Language Server Protocol, with install instructions on the project website and separate badge links for the VS Code, NeoVim and command line or other routes.

That third category is the one to understand properly. Because the server is a standalone program that speaks LSP over standard input and output, it is not tied to any editor. The repository root contains an executable `lua-language-server` entry, and the tree also holds a rockspec, `make.lua`, `make.bat`, `make.sh` and a `make/` directory, which together describe building and running the binary outside the extension.

The README also names community-maintained install methods rather than pretending to own them. The one listed is an asdf plugin, maintained by a community member, which is the route to take if you manage editor tool versions with asdf. Related searches turn up Linux distribution packages and an npm route, both of which exist outside this repository.

For support, the README points at the changelog on the master branch, the wiki, an FAQ page, the issue tracker for both bugs and feature suggestions, and Discussions. The issue tracker doubles as the feature request channel, which is how most of the 708 open issues accumulate.

## Translations are community-run, and one has a reporting path

The README lists six available languages: `en-us`, `zh-cn`, `zh-tw`, `pt-br`, `ja-jp` and `es-419`. Each is paired with a flag, and each flag carries a political or regional framing that you should read as documentation of the locale rather than as a statement. The README also states that all translations are provided and collaborated on by the community, and asks that an inappropriate or harmful translation be reported immediately through the issue tracker.

That is an unusual and somewhat telling detail. A project that explicitly invites reports about harmful translations is signalling that it has had to deal with them, which for a tool with this reach in Chinese-speaking and Japanese-speaking communities is unsurprising.

The README asks for help with translations generally and links a translations page on the wiki, then thanks contributors of translations with a link to the locale commit history. The tree confirms the layout with a `locale/` directory.

Two separate README lines invite contributions in the same spirit: one asking readers to report mistakes or open a pull request with a fix, and a second line repeating the request in Chinese with a link to the issue tracker and to pull requests. That pattern, an English request followed by a Chinese one, is a small indicator of where a large share of the contributor base sits.

## Telemetry is gone, and the release history is all type fidelity

The Privacy section is short and unambiguous. The language server had opt-in telemetry that collected usage data and sent it to the development team to help improve the extension, and telemetry was removed in `v3.6.5` and is no longer part of the language server. For a language server that sees every keystroke-level edit you make, that removal is the single most privacy-relevant fact in the repository.

Recent releases read as a long argument with the Lua standard library's own documentation. Version 3.19.0, published 2026-08-07, fixes `osdate` field types to match the Lua manual, corrects the `math.type` return annotation, fixes `string.match` and `string.gmatch` so they may return string, number or nil, and adds type inference for `@field` and `@type` in method overrides plus generic parameter resolution in `@operator` declarations. Version 3.19.1 a week later contains a single change, described only as fix deepseek, which refers to AI code review integration added in 3.19.0 alongside DeepSeek reviews.

The pattern is worth naming: this project's bugs are mostly type inaccuracies in its own annotations of the standard library. A wrong annotation produces a wrong diagnostic in someone else's editor, so each release is a correction pass against the Lua manual. That is unglamorous and it is the bulk of the maintenance work.

The repository also carries a `changelog.md`, a `meta/` directory, `doc/`, `script/`, `tools/`, a `test/` directory, `3rd/` for vendored dependencies, `.luarc.json` as the default configuration, `.pre-commit-hooks.yaml` so the formatter can run in commit hooks, and `theme-tokens.md` for editor colour themes.

## A Dockerfile still pinned to Ubuntu 18.04 and gcc-9

The `Dockerfile` at the repository root is short and dated. It starts from `ubuntu:18.04`, adds the Ubuntu toolchain test PPA and the git-core PPA, installs git, gcc-9, g++-9, wget, tar, gzip, rsync and ninja-build, then registers the alternatives so that gcc-9 and g++-9 become the default gcc and g++.

Set that beside the language coverage and the project takes on an odd double character. The server supports Lua 5.5 and LuaJIT and describes itself as actively developed, while its own containerized build pins a compiler release that predates all of that and an operating system that has been out of standard support for years. There is also `zig-cc-wrapper.sh` in the tree, which suggests a newer compiler path exists alongside the older one.

Nothing here is a functional problem. A Dockerfile is a build convenience, and the reason to pin an old toolchain is usually that a native dependency or a bundled C component needs a known-good compiler. But if you are deciding how much confidence to place in the project's build, the honest reading is that the canonical container path has not been revisited, and the presence of the zig wrapper suggests active work is happening in a different direction than the Dockerfile reflects.

The build files tell a similar story from another angle: `make.sh`, `make.bat` and `make.lua` cover Linux, Windows and the Lua-driven build, and the rockspec supports installation through LuaRocks. Together with the credit list in the README, which names bee.lua, luamake, LPegLabel, LuaParser, json.lua, inspect.lua, EmmyLua and EmmyLuaCodeStyle among others, that is a large dependency surface for a tool people run in their editor on every keystroke.

## Conclusion

lua-language-server is the reference implementation for what Lua tooling can be, and its annotations are the part worth studying: they turn a dynamically typed language into one where a type checker has something to read. For most teams the practical path is the Visual Studio Code extension rather than a manual install, and for editor-switchers the Neovim path works because the project is a plain language server. Two things to know before depending on it. First, the type checking is opt-in and configured per workspace, so the out-of-the-box experience is diagnostics plus completions rather than full inference. Second, the repository's `Dockerfile` is still based on ubuntu 18.04 with gcc-9, which tells you the build toolchain has not been modernized even though the language coverage now runs to Lua 5.5.

## FAQ

### How to install Lua language server?

The README states the server can be installed for use in Visual Studio Code, NeoVim, or any other client that supports the Language Server Protocol, and points to luals.github.io for the step-by-step instructions. A community-maintained asdf plugin is also listed for version-managed setups.

### Which Lua versions does lua-language-server support?

The README lists `Lua 5.5`, `Lua 5.4`, `Lua 5.3`, `Lua 5.2`, `Lua 5.1` and `LuaJIT`. Because type checking is dynamic rather than compiled, the supported version determines which standard library annotations the analyzer applies.

### Does lua-language-server collect any usage data?

No. The README states the language server had opt-in telemetry that sent usage data to the development team, and that telemetry was removed in v3.6.5 and is no longer part of the language server. A privacy policy page remains linked for the historical detail.

### What are LuaLS annotations for?

They are how you document types in code that has none natively. The README lists over 20 supported annotations for documenting code, and the wiki carries the full reference. Recent releases have focused on making annotations accurate, including osdate field types, math.type returns and string.match and string.gmatch return types.

## Sources

- [License: MIT](https://github.com/LuaLS/lua-language-server/blob/master/LICENSE)
- [LuaLS/lua-language-server on GitHub](https://github.com/LuaLS/lua-language-server)
- [Project website](https://luals.github.io)
- [README](https://github.com/LuaLS/lua-language-server/blob/master/README.md)
- [Releases](https://github.com/LuaLS/lua-language-server/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/luals-lua-language-server