A luxurious package manager for Lua.
Key Features • How To Use • Comparison with Luarocks • Related Projects • Contributing
- Create and manage Lua projects
- Easily manage dependencies, build steps and more through the
lux.tomlfile.
- Easily manage dependencies, build steps and more through the
- Parallel builds and installs 🚀
- Add/remove dependencies with simple CLI commands
- Automatic generation of rockspecs
- Say goodbye to managing 10 different rockspec files in your source code 🎉
- Integrated code formatting via
lx fmt- Powered by stylua.
- Easily specify compatible Lua versions
- Lux will take care of Lua header installation automatically
- Forget about users complaining they have the wrong Lua headers installed on their system
- Automatic code linting via
lx check- Powered by
luacheck.
- Powered by
- Powerful lockfile support
- Makes for fully reproducible developer environments.
- Makes Lux easy to integrate with Nix!
- Fully compatible
- Works with existing luarocks packages.
- Have a complex rockspec that you don't want to rewrite to TOML? No problem!
Lux allows the creation of an
extra.rockspecfile, everything just works. - Have a very complex build script? Lux can shell out to
luarocksif it knows it has to preserve maximum compatibility.
Warning
Lux, while generally functional, is a work in progress
and does not have a 1.0 release yet.
Feel free to consult the documentation on how to get started with Lux!
It features a tutorial and several guides to make you good at managing Lua projects.
As this project is still a work in progress, some luarocks features have not been (fully) implemented yet. On the other hand, lux has some features that are not present in luarocks.
The following table provides a brief comparison:
| lux | luarocks v3.11.1 | |
|---|---|---|
| project format | TOML / Lua | Lua |
| add/remove dependencies | ✅ | ❌ |
| parallel builds/installs | ✅ | ❌ |
| proper lockfile support with integrity checks | ✅ | ❌ (basic, dependency versions only) |
| run tests with busted | ✅ | ✅ |
| linting with luacheck | ✅ | ❌ |
| code formatting with stylua | ✅ | ❌ |
| automatic lua detection/installation | ✅ | ❌ |
| default build specs | ✅ | ✅ |
| custom build backends | ✅1 | ✅ |
rust-mlua build spec |
✅ (builtin) | ✅ (external build backend) |
treesitter-parser build spec |
✅ (builtin) | ✅ (external build backend) |
| install pre-built binary rocks | ✅ | ✅ |
| install multiple packages with a single command | ✅ | ❌ |
| install packages using version constraints | ✅ | ❌ |
auto-detect external dependencies and Lua headers with pkg-config |
✅ | ❌ |
| resolve multiple versions of the same dependency at runtime | ✅ | ✅ |
| pack and upload pre-built binary rocks | ✅ | ✅ |
| luarocks.org manifest namespaces | ✅ | ✅ |
| luarocks.org dev packages | ✅ | ✅ |
| versioning | SemVer2 | arbitrary |
| rockspecs with CVS/Mercurial/SVN/SSCM sources | ❌ (YAGNI3) | ✅ |
| static type checking | ❌ (planned) | ❌ |
| git dependencies in local projects | ✅ | ❌ |
Lux includes the following packages and libraries:
-
lux-cli: The main CLI for interacting with projects and installing Lua packages from the command line. -
lux-lua: The Lux Lua API, which provides:lux.loaderfor resolving dependencies onrequireat runtime.- A work-in-progress API for embedding Lux into Lua applications.
We provide builds of
lux-luafor Lua 5.1, 5.2, 5.3, 5.4 and Luajit.lux-cliuseslux-luafor commands likelx lua,lx runandlx path.
-
lux-lib: The Lux library for Rust. A dependency oflux-cliandlux-lua.
Note
We do not yet provide a way to install lux-lua as a Lua library using Lux.
See #663.
Lux can detect a lux-lua installation using pkg-config
or via the LUX_LIB_DIR environment variable.
Dependencies:
openssllibgit2gnupg,libgpg-errorandgpgme(*nix only)lua(optional, if building without thevendored-luafeature)
We recommend building with the vendored-lua feature enabled:
cargo build --features vendored-luaYou can build lux-lua for a given Lua version with:
cargo xtask51 dist-lua # lux-lua for Lua 5.1
cargo xtask52 dist-lua # for Lua 5.2
cargo xtask53 dist-lua # ...
cargo xtask54 dist-lua
cargo xtaskjit dist-luaThis will install lux-lua to target/dist/<lua>/lux.so
and a pkg-config .pc file to target/dist/lib/lux-lua*.pc.
If you would like to use the latest version of lux with Nix, you can import our flake. It provides an overlay and packages for:
lux-cli: The Lux CLI package.lux-lua51The Lux Lua API for Lua 5.1lux-lua52The Lux Lua API for Lua 5.2lux-lua53The Lux Lua API for Lua 5.3lux-lua54The Lux Lua API for Lua 5.4lux-luajitThe Lux Lua API for Luajit
If you have a lux-lua build and pkg-config in a Nix devShell,
Lux will auto-detect lux-lua.
- luarocks - The original Lua package manager
- rocks.nvim - A Neovim plugin manager that uses
luarocksunder the hood, and will soon be undergoing a rewrite to use Lux instead.
Credits go to the Luarocks team for maintaining luarocks and luarocks.org for as long as they have. Without their prior work Lux would not be possible.
Contributions are more than welcome! See CONTRIBUTING.md for a guide.
- Lux is licensed under MIT.
- The Lux logo © 2025 by Kai Jakobi is licensed under CC BY-NC-SA 4.0.
Footnotes
-
Supported via a compatibility layer that uses luarocks as a backend. ↩
-
Mostly compatible with the luarocks version parser, which allows an arbitrary number of version components. To comply with SemVer, we treat anything after the third version component (except for the specrev) as a prerelease/build version. ↩