Luau: a Lua 5.1-compatible language with a gradual type system for embedding

The problem Luau solves for embedders

Embedding Lua 5.1 gives you a fast scripting layer with a tiny footprint, and no way to catch a typo in a field name until the script runs. Luau targets that gap. The README describes it as "a fast, small, safe, gradually typed embeddable scripting language derived from Lua", and the gradual part is the point: type annotations are optional, so untyped Lua 5.1 code still parses and runs, while annotated code gets checked by luau-analyze before it ever reaches production.

The audience is narrower than "anyone using Lua". Luau is aimed at hosts that ship a scripting runtime inside a larger application and want tooling around it. The README names the pattern directly: Roblox game developers write game code in Luau, Roblox engineers implement large parts of the user-facing application and parts of Roblox Studio as plugins, and the README also lists Alan Wake 2, Farming Simulator 2025, Second Life and Warframe as adopters. Those are all cases where a host application exposes an API to scripts written by someone else. If you are writing a standalone Lua program for your own machine, Luau's embedding machinery is mostly overhead you will not use.

How the runtime, compiler and analyzer fit together

The repository layout mirrors the pipeline. Ast, Compiler and Bytecode handle source to bytecode. VM holds the runtime, described in the README as a heavily modified Lua 5.1 runtime with a completely rewritten interpreter. Analysis holds the type checker and linter. Require, Config and CodeGen cover module resolution, .luaurc configuration and code generation. The Makefile builds each as a separate static library: libluauast.a, libluaucompiler.a, libluaubytecode.a, libluauvm.a, libluauanalysis.a, plus libluaucommon.a, libluauconfig.a, libluaurequire.a and libluaujitinliner.a.

That split is deliberate, and the README explains why: source is compiled to bytecode separately from loading it, "which is important to be able to deploy VM without a compiler". A host that receives precompiled bytecode can link only Luau.VM and skip the compiler entirely. The README states that integrating into a CMake project requires depending on Luau.Compiler and Luau.VM at minimum.

The safeenv feature is the other architectural decision worth knowing about. The README calls it "highly recommended" and describes it as sandboxing individual scripts' global tables from each other while protecting builtin libraries from monkey-patching. Enabling it requires two calls: luaL_sandbox on the global state, and luaL_sandboxthread for each new script's execution thread. If you skip those, you get Lua's usual shared-globals behavior, where one script can overwrite a builtin that another script depends on.

Installing Luau and running a first checked script

The README gives two paths. Download compiled binaries from a recent release and put the luau and luau-analyze binaries on PATH or copy them to a directory like /usr/local/bin on Linux and macOS. Or use a packaged distribution, which the README notes is not maintained by the Luau development team: brew install luau on macOS, pacman -Syu luau on Arch, apk add luau on Alpine, and emerge dev-lang/luau on Gentoo, possibly with --autounmask=y.

To build from source with CMake, the README gives these commands:

mkdir cmake && cd cmake
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build . --target Luau.Repl.CLI --config RelWithDebInfo
cmake --build . --target Luau.Analyze.CLI --config RelWithDebInfo

On Linux and macOS the Makefile offers a shorter route, building both CLI targets in one command:

make config=release luau luau-analyze

After installing, the README points at the test case on luau.org/getting-started to validate the install. The luau binary is a REPL and a file runner, and the README warns that the REPL runs sandboxed: it has no filesystem access except the ability to require modules. That catches people who expect a Lua-style shell where os and io are available.

The second binary is the one that changes daily work. luau-analyze takes a set of input files and produces errors and warnings based on file configuration, which can be set with --! comments inside the files or with .luaurc files. So a typical first real use is pointing it at an existing Lua 5.1 codebase and reading the warnings, then deciding which ones to silence through .luaurc rather than by editing every file. The README links to luau.org/typecheck and luau.org/lint for the details of what those checks are; it does not enumerate them.

Where Luau stops being a drop-in Lua replacement

The README is explicit that the runtime "mostly preserves Lua 5.1 API, so existing bindings should be more or less compatible with a few caveats". The word mostly is doing real work there, and the README names one caveat outright: no __gc support. The replacement is lua_newuserdatadtor. If your C bindings rely on __gc to release resources attached to userdata, that is a code change, not a configuration flag, and it is the kind of thing that surfaces at runtime rather than at compile time.

The second caveat is structural. Source must be compiled separately before loading, so any host code that assumes it can hand a string to a combined compile-and-run entry point needs rework. The README frames this as a feature for deployment, and it is, but it is also a migration cost.

A third limitation is visible in the tooling rather than the runtime. The README states that a language server frontend for luau-analyze, luau-lsp, is maintained by the community, not by the Luau development team. Editor integration therefore lives outside this repository, and the README does not describe its release cadence or compatibility guarantees.

Finally, Luau is the wrong tool if you specifically need Lua 5.4 semantics. The README says Luau is backwards compatible with Lua 5.1 and incorporates "some features" from future Lua releases, not all of them. If your code depends on integer division semantics or other 5.3+ behavior, check the compatibility page before assuming it is there.

Luau versus Lua when you are choosing a runtime

The honest comparison is not Luau against a competitor product; it is Luau against upstream Lua, because Luau starts from Lua 5.1 and diverges in two directions at once. Upstream Lua keeps a small, stable C API and adds no static analysis. Luau keeps the API shape but rewrites the interpreter, adds a type inference system, and ships a separate analyzer binary. The README describes the language runtime as "a very heavily modified version of Lua 5.1 runtime" with performance innovations documented at luau.org/performance.

So the trade is this. Choosing upstream Lua means your bindings are portable across every Lua-embedding project and you never think about a compiler/VM split. Choosing Luau means you get luau-analyze in CI and the safeenv sandboxing model, at the cost of adapting bindings around the caveats above and adopting a language that evolves through its own RFC process in the rfcs repository rather than through lua.org.

There is a third option worth naming: stay on Lua 5.1 and add a separate static checker for Lua. That keeps your runtime untouched, but you do not get Luau's type inference, and you do not get a checker that was designed alongside the language it checks. Which of those matters depends on whether your scripts are written by your own team or by users of your product.

Release cadence, licence and what upgrades cost

Releases are frequent and versioned by a simple incrementing number. The three most recent listed are 0.739 on 2026-09-18, 0.738 on 2026-09-11 and 0.737 on 2026-09-04, roughly weekly. The last push to the repository was on 2026-09-22. That cadence is a real operational consideration: if you vendor a Luau release, you are choosing how far behind to sit, and there is no long-term support branch described in the README.

The licence is MIT for the Luau implementation, and the README notes it is based on the Lua 5.x implementation, also under MIT. The repository carries both LICENSE.txt and lua_LICENSE.txt, which reflects that dual provenance. Two things follow without giving legal advice: MIT is permissive, and if you redistribute binaries you should carry the licence text and the copyright notice that the licence requires. If your legal team cares about provenance, the presence of two licence files is worth pointing out to them rather than discovering later.

On build dependencies, the README is specific: the runtime requires C++11, the compiler and analysis components require C++17, and it builds with Visual Studio 2017 or later, gcc-7 or clang-7 or later. Library components have no external dependencies beyond the STL and CRT. The test suite pulls in doctest and the REPL pulls in isocline. That matters if you build from source in a constrained environment: the runtime alone has a lower C++ standard requirement than the compiler and analyzer, consistent with the goal of deploying a VM without a compiler.

Editorial conclusion

Adopt Luau if you are embedding a scripting layer and want Lua 5.1 compatibility plus a type checker and linter you can run in CI. Do not adopt it if your existing bindings depend on __gc or on a Lua runtime API you cannot adjust, because the README states Luau deviates from Lua 5.x in places. Before committing, verify two things yourself: that your bindings compile against the current VM headers, and that the .luaurc configuration accepts the analysis settings your codebase needs. Both are checkable in an afternoon with the luau-analyze binary and your own source tree.

Frequently asked questions

Official sources

1. License: MIT
2. luau-lang/luau on GitHub
3. Project website
4. README
5. Releases