Lux

A luxurious package manager for Lua.

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

:star2: Key Features

:package: Create and Manage Lua Projects

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

:gear: 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.

:tada: Automatic Generation of Rockspecs

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

:jigsaw: 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.

:lock: Advanced Lockfile Support

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

:globe_with_meridians: 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.

:gear: 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.

:bar_chart: 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	:white_check_mark:	:x:
Parallel builds/installs	:white_check_mark:	:x:
Proper lockfile support with integrity checks	:white_check_mark:	:x: (basic, dependency versions only)
Run tests with busted	:white_check_mark:	:white_check_mark:
Linting with luacheck	:white_check_mark:	:x:
Code formatting with stylua, luafmt, or emmylua_codestyle	:white_check_mark:	:x:
Automatic lua detection/installation	:white_check_mark:	:x:
Default build specs	:white_check_mark:	:white_check_mark:
Custom build backends	:white_check_mark:1	:white_check_mark:
rust-mlua build spec	:white_check_mark: (builtin)	:white_check_mark: (external build backend)
treesitter-parser build spec	:white_check_mark: (builtin)	:white_check_mark: (external build backend)
Install prebuilt binary rocks	:white_check_mark:	:white_check_mark:
Install multiple packages with a single command	:white_check_mark:	:x:
Install packages using version constraints	:white_check_mark:	:x:
Auto-detect external dependencies and Lua headers with pkg-config	:white_check_mark:	:x:
Resolve multiple versions of the same dependency at runtime	:white_check_mark:	:white_check_mark:
Pack and upload prebuilt binary rocks	:white_check_mark:	:white_check_mark:
Luarocks.org manifest namespaces	:white_check_mark:	:white_check_mark:
Luarocks.org dev packages	:white_check_mark:	:white_check_mark:
Versioning	SemVer2	arbitrary
Rockspecs with CVS/Mercurial/SVN/SSCM sources	:x: (YAGNI3)	:white_check_mark:
Load installed packages from multiple install trees	:x: (#1493)	:white_check_mark:
Static type checking	:white_check_mark:	:x:
Generate a .luarc file with dependencies	:white_check_mark:	:x:
Git dependencies in local projects	:white_check_mark:	:x:
Local dependencies in local projects	:white_check_mark:	:x:
Multiple projects in a single workspace	:white_check_mark:	:x:
Vendor sources for offline use	:white_check_mark:	:x:
Distribute install tree archives	:white_check_mark:	:x:
Distribute static binaries	:white_check_mark:	:x:
Load RockSpecs and LuaRocks manifests with full sandboxing	:white_check_mark:	:x:
Sandbox build execution	:white_check_mark: 4	:x:

:package: 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.

:wrench: 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

:snowflake: 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.

:bulb: 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.

:purple_heart: 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.

:green_heart: Contributing

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

:book: 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. ↩