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.

[!NOTE]

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

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

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

[!NOTE]

Lux can detect a lux-lua installation using pkg-config or via the LUX_LIB_DIR environment variable.

Our prebuilt binary release artifacts are bundled with 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 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 xtask55 dist-lua
cargo xtaskjit dist-lua

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.

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