Lux

A luxurious package manager for Lua.

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

:star2: Key Features

• Create and manage Lua projects
  • Easily manage dependencies, build steps and more through the lux.toml file.
• Parallel builds and installs :rocket:
• Add/remove dependencies with simple CLI commands
• Automatic generation of rockspecs
  • Say goodbye to managing 10 different rockspec files in your source code :tada:
• 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 EmmyLua/LuaCATS based type checking via lx check
  • Powered by emmylua-analyzer-rust
• Automatic code linting via lx lint
  • Powered by luacheck
• 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.rockspec file, everything just works.
  • Have a very complex build script? Lux can shell out to luarocks if it knows it has to preserve maximum compatibility.
• Automatically adds project dependencies to a .luarc.json file so they can be picked up by lua-language-server.

[!WARNING]

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

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

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

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.

Our pre-built 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:

• lua
• 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 lua, 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 lua54,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 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-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.