luainstaller

Turn a Lua script into a program you can hand to someone else.

luainstaller collects your script, the modules it loads with require, and the Lua runtime, and builds a native executable from them. The person running it doesn’t need Lua installed.

luai -b app/main.lua -o build/app   # (1)
build/app/app                       # (2)

1. Build a directory bundle from your entry script.

2. Run it. No lua on the machine is required.

It works with official Lua 5.1 through 5.5 on Linux, Windows (back to XP), macOS, FreeBSD and Android/Termux.

Contents

• Install
• Build your first executable
• Use it from Lua
• Where it runs
• Documentation
• License

Install

luarocks install luainstaller
luai -v

LuaRocks is optional. Without it, install from a source checkout into a directory of your choice:

lua tools/install.lua --prefix "$HOME/luainstaller"
export PATH="$HOME/luainstaller/bin:$PATH"

Details, including Windows and moving or removing an install, are in Installing without LuaRocks.

What you need to build executables

• An official Lua interpreter, 5.1 to 5.5. LuaJIT isn’t supported.

• A C compiler for the machine you’re on.

• Lua headers and a Lua library that match that interpreter’s version.

Analysis works with just Lua. Only building needs the compiler.

💡	On most Linux systems the headers come from a package such as liblua5.4-dev or lua-devel.

Build your first executable

The safe path is: check the dependencies, build a folder, test the folder, and only then make a single file.

1. See what will be packaged.

   luai -a app/main.lua

   This lists every module luainstaller found for your script. If something is missing here, it will be missing from the executable too.

2. Build a directory bundle.

   luai -b app/main.lua -o build/app

   You get build/app/app (or app.exe on Windows) plus a hidden .luai/ folder with native modules and license files.

3. Test it the way your users will run it.

   env -u LUA_PATH -u LUA_CPATH build/app/app

   Clearing the Lua search paths makes sure the program isn’t quietly loading modules from your own machine.

4. Make a single file, if you want one.

   luai -b --file app/main.lua -o build/app-onefile

   The single file unpacks itself to a temporary folder on first run and starts from there.

❗	If the single file misbehaves, go back to the directory bundle. It shows exactly what was packaged, so problems are much easier to find.

Two command styles

The same tool answers to two names. Pick whichever you like, but don’t mix them in one command.

Task	luai (short options)	luainstaller (subcommands)
Analyze	luai -a main.lua	luainstaller analyze main.lua
Trace	luai -t main.lua	luainstaller trace main.lua
Build	luai -b main.lua	luainstaller build main.lua
Version	luai -v	luainstaller version
Help	luai -h	luainstaller help
View logs	—	luainstaller logs

Options you’ll actually use

--dir / --file	folder bundle (default) or single executable
-o PATH	where to write the result
--max-deps N	raise this for large programs; the default is 36
--include FILE	add a module the scan couldn’t see
-d runtime	find dependencies by actually running the script

Everything else is in the usage guide.

Use it from Lua

The same features are available as a library:

local luainstaller = require("luainstaller")

local result = luainstaller.bundle({
    entry = "app/main.lua",
    out = "build/app",
})

if result.ok then
    print("built " .. result.executable)
else
    print(result.error.type .. ": " .. result.error.message)
end

Every call returns a table with ok. On failure, error.type names the problem. Options match the command line; see Library API.

Where it runs

luainstaller builds for the machine it runs on. To get a Windows executable, build on Windows; for macOS, build on a Mac.

System	CPU	Notes
Windows XP SP3 and later	x86, x86_64	Needs an XP-capable compiler and runtime.[1]
Windows 7 and later	x86, x86_64, ARM, ARM64	MSVC or MinGW
Linux	x86, x86_64, ARM, ARM64	Shared or static Lua
macOS	x86_64, ARM64	Static Lua preferred
FreeBSD	native
Android (Termux)	native	Runs inside the Termux app

Other Unix-like systems often work too, as long as the compiler and Lua library match.

🔥	Native C modules (anything built as .so or .dll) are copied as-is. They must already be built for the target system and your Lua version.

Documentation

Install	Installing without LuaRocks, on Linux, macOS and Windows
Usage	All options, dependency discovery, native modules, the library API
Troubleshooting	Common errors and how to fix them
Platforms	Compilers per system, Windows XP, native modules, what’s out of scope
Bundle format	What’s inside a bundle and how it starts
Licenses and relinking	What to keep when you redistribute an executable
Changelog	Changes between releases

For contributors

• Implementation notes — how the code is laid out

• Testing — test suites and CI

License

luainstaller is released under the GNU LGPL, version 3 or later.

Every bundle includes the Lua license, the luainstaller license, and the generated C source, so you can pass it on as-is. Keep the .luai/ folder when you redistribute. Relinking explains why.

---

1. A modern Visual Studio or UCRT build won’t start on XP. See Platforms.