Lux

A luxurious package manager for Lua.

Key Features • How To Use • Comparison with LuaRocks • Related Projects • Contributing

🌟 Key Features

📦 Create and Manage Lua Projects

• Easily manage dependencies, build steps and more through the lux.toml file.
• Full support for existing .rockspec files.

⚙️ Modern, Comfortable Tooling

• Parallel builds and installs.
• Add/remove dependencies with simple CLI commands.
• Integrated code formatting, type checking and powerful code linting.
• Good DX - automatically adds project dependencies to .luarc.json for rich LSP diagnostics.
• Distribute projects (including dependencies) as install tree archives or as static binaries without the need for a Lua installation.

🎉 Automatic Generation of Rockspecs

• Say goodbye to managing 10 different rockspec files in your source code!

🧩 Lua Versioning Done Easy

• Lux takes care of installing the right versions of Lua headers automatically.
• Forget about users complaining they have the wrong Lua installed on their system.

🔒 Advanced Lockfile Support

• Fully reproducible developer environments.
• Makes Lux easy to integrate with Nix!

🌐 Fully Compatible with the Ecosystem

• 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.rockspec file, everything just works.
• Have a very complex build script? Lux can shell out to luarocks if it detects it has to preserve maximum compatibility.

⚙️ How To Use

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.

Note

Lux, while fully functional, is a work in progress and does not have a 1.0 release yet.

📊 Comparison with LuaRocks

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.13.0
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, luafmt, or emmylua_codestyle	✅	❌
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 prebuilt 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 prebuilt binary rocks	✅	✅
Luarocks.org manifest namespaces	✅	✅
Luarocks.org dev packages	✅	✅
Versioning	SemVer2	arbitrary
Rockspecs with CVS/Mercurial/SVN/SSCM sources	❌ (YAGNI3)	✅
Load installed packages from multiple install trees	❌ (#1493)	✅
Static type checking	✅	❌
Generate a .luarc file with dependencies	✅	❌
Git dependencies in local projects	✅	❌
Local dependencies in local projects	✅	❌
Multiple projects in a single workspace	✅	❌
Vendor sources for offline use	✅	❌
Distribute install tree archives	✅	❌
Distribute static binaries	✅	❌
Load RockSpecs and LuaRocks manifests with full sandboxing	✅	❌
Sandbox build execution	✅ 4	❌

📦 Packages

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.loader for resolving dependencies on require at runtime.
  • A work-in-progress API for embedding Lux into Lua applications. We provide builds of lux-lua for Lua 5.1, 5.2, 5.3, 5.4, 5.5 and LuaJIT. lux-cli uses lux-lua for commands like lx lua, lx run and lx path.

• lux-lib: The Lux library for Rust. A dependency of lux-cli and lux-lua.

Note

Lux can detect a lux-lua installation using pkg-config or pkgconf.

Our prebuilt binary release artifacts are bundled with lux-lua.

🔧 Building from source

Dependencies:

• gnupg, libgpg-error and gpgme (*nix only)

If building without the vendored feature:

• libgit2
• openssl

If building with the vendored feature:

• perl and perl-core
• make

To link gpgme statically on Linux and macOS, set the environment variable SYSTEM_DEPS_LINK=static.

We usually recommend building with the vendored feature enabled, to statically link libgit2 and openssl:

SYSTEM_DEPS_LINK="static" cargo build --locked --profile release --features vendored

Or, to build with dynamically linked libraries:

cargo build --locked --profile release

On Windows/MSVC, you must disable the gpgme feature:

cargo build --locked --profile release --no-default-features --features vendored

You can build lux-lua for a given Lua version with:

cargo xtask-lua51 dist # lux-lua for Lua 5.1
cargo xtask-lua52 dist # for Lua 5.2
cargo xtask-lua53 dist # ...
cargo xtask-lua54 dist
cargo xtask-lua55 dist
cargo xtask-luajit dist

This will install lux-lua to target/dist/share/lux-lua/<lua>/lux.so and a pkg-config .pc file to target/dist/lib/lux-lua*.pc.

By default, the $prefix in the generated .pc file is ${{pcfiledir}}/../../share/lux-lua/. You can override it by setting LUX_LIB_DIR, for example:

LUX_LIB_DIR="/usr/lib/lua/5.1" cargo xtask-lua51 dist

To build completions:

cargo xtask dist-completions

To build man pages:

cargo xtask dist-man

To build the binary distributions for your platform, bundled with completions, man pages and lux-lua:

cargo xtask dist-package

❄️ Nix flake

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-lua51 The Lux Lua API for Lua 5.1
• lux-lua52 The Lux Lua API for Lua 5.2
• lux-lua53 The Lux Lua API for Lua 5.3
• lux-lua54 The Lux Lua API for Lua 5.4
• lux-lua55 The Lux Lua API for Lua 5.5
• lux-luajit The 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.

💡 You may also like...

• LuaRocks - The original Lua package manager
• rocks.nvim - A Neovim plugin manager that uses luarocks under the hood, and will soon be undergoing a rewrite to use Lux instead.

💜 Credits

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.

💚 Contributing

Contributions are more than welcome! See CONTRIBUTING.md for a guide.

📖 License

• Lux is licensed under LGPL-3.0+.
• The Lux logo © 2025 by Kai Jakobi is licensed under CC BY-NC-SA 4.0.
• The nix helper functions in the nix/ are licensed under the MIT No Attribution License (MIT-0).

Footnotes

1. Supported via a compatibility layer that uses LuaRocks as a backend. ↩

2. Aims to be compatible with the LuaRocks version parser, which allows an arbitrary number of version components. We treat anything after the third version component (except for the specrev) as a prerelease/build version, but allow comparing versions with/without prerelease components. ↩

3. You Aren't Gonna Need It. ↩

4. Opt-in via a build.runner config. ↩