Format:Lua bytecode
| Developer | PUC-Rio |
|---|---|
| Versions | 5.1 (0x51), 5.2 (0x52), 5.3 (0x53), 5.4 (0x54), 5.5 (0x55) |
| Magic | 1B 4C 75 61 ("\x1bLua") + version byte 0x51-0x55 + format byte 00 |
| Extensions | .luac, .lub, luac.out (luac's default output name); often inside archives with .lua names |
| Endianness | native (as recorded in the header) |
| License | MIT (reference implementation) |
| On this wiki | Facts · Code · Notes · Topics |
Precompiled chunk format of the Lua reference implementation, written by luac, lua_dump and string.dump: the signature 1B 4C 75 61 ('\x1bLua'), a version byte (0x51 to 0x55), a header of type sizes and test values, then the main function prototype with its code, constants, upvalues, nested functions and optional debug information. Every minor version has its own incompatible layout.
Overview
A precompiled chunk is the serialised main function of a Lua script: Library:Lua's luaU_dump (ldump.c) writes it for the luac compiler, the C function lua_dump and the Lua function string.dump; luaU_undump (lundump.c) reads it whenever a chunk given to load/luaL_loadbuffer starts with the byte 0x1B. The format is not portable: each minor version has its own layout, and the header records the sizes of the C types (and, in 5.1/5.2, the byte order) of the machine that wrote it; the loader rejects any mismatch. There is no checksum and no verifier: the manual warns that "maliciously crafted binary chunks can crash the interpreter".
With strip (luac -s, string.dump(f, true), lua_dump(L, w, d, 1) in 5.3+) the debug information (line info, local and upvalue names, source name) is left out; constants, string literals and global names stay. The luacinfo script parses all five layouts and disassembles them; luascan finds chunk headers and the interpreter itself inside other files.
Identification
The file starts with 1B 4C 75 61 ("\x1bLua"), then the version byte major*16+minor (0x51 to 0x55) and the format byte 0x00 (official format). From 5.2 the header contains LUAC_DATA 19 93 0D 0A 1A 0A ("\x19\x93\r\n\x1a\n", 1993 is Lua's birth year; the CR LF and ^Z catch text-mode transfer damage): right after the format byte in 5.3-5.5, after six size bytes in 5.2. A LuaJIT dump (Format:LuaJIT bytecode) starts with 1B 4C 4A instead.
First bytes written by MSVC x64 builds (default luaconf.h):
- 5.1:
1B 4C 75 61 51 00 01 04 08 04 08 00 - 5.2:
1B 4C 75 61 52 00 01 04 08 04 08 00 19 93 0D 0A 1A 0A - 5.3:
1B 4C 75 61 53 00 19 93 0D 0A 1A 0A 04 08 04 08 08 78 56 00 00 00 00 00 00 00 00 00 00 00 28 77 40 - 5.4:
1B 4C 75 61 54 00 19 93 0D 0A 1A 0A 04 08 08 78 56 00 00 00 00 00 00 00 00 00 00 00 28 77 40 - 5.5:
1B 4C 75 61 55 00 19 93 0D 0A 1A 0A 04 88 A9 FF FF 04 78 56 34 12 08 88 A9 FF FF FF FF FF FF 08 00 00 00 00 00 28 77 C0
Other embedded Lua-family VMs do not share this header: Luau starts with a bare version byte (Format:Luau bytecode), LuaJIT with 1B 4C 4A (Format:LuaJIT bytecode).
Header
| Version | Size | After signature, version and format bytes |
|---|---|---|
| 5.1 | 12 | endianness (1 = little), sizeof(int), sizeof(size_t), sizeof(Instruction), sizeof(lua_Number), integral flag (1 if lua_Number is an integer type) |
| 5.2 | 18 | the same six bytes, then LUAC_TAIL 19 93 0D 0A 1A 0A
|
| 5.3 | 33 | LUAC_DATA, sizeof(int), sizeof(size_t), sizeof(Instruction), sizeof(lua_Integer), sizeof(lua_Number), LUAC_INT 0x5678 as a lua_Integer, LUAC_NUM 370.5 as a lua_Number |
| 5.4 | 31 | LUAC_DATA, sizeof(Instruction), sizeof(lua_Integer), sizeof(lua_Number), 0x5678, 370.5 (int and size_t are no longer fixed-size in the file) |
| 5.5 | 40 | LUAC_DATA, then four (size byte, test value) pairs: int -0x5678, Instruction 0x12345678, lua_Integer -0x5678, lua_Number -370.5 |
The byte order of 5.3 and later is not stored; a reader finds it from the test integer. In 5.3, 5.4 and 5.5 one more byte follows the header: the number of upvalues of the main function (1, _ENV). 5.1 and 5.2 have no such byte. The sizes are for the default 64-bit lua_Integer/lua_Number; the header layouts are also struct facts, so export_header with subject Format:Lua bytecode gives them as C structs.
Function prototype
After the header comes the main function; nested functions use the same layout recursively. Field order:
- 5.1: source (string), linedefined, lastlinedefined (int), nups, numparams, is_vararg, maxstacksize (bytes), code (int n, n instructions), constants (int n, tagged values), nested functions (int n, functions), lineinfo (int n, n ints), locvars (int n, each: name string, startpc, endpc), upvalue names (int n, strings).
- 5.2: linedefined, lastlinedefined, numparams, is_vararg, maxstacksize, code, constants, nested functions, upvalues (int n, each: instack byte, idx byte), then the debug part: source, lineinfo, locvars, upvalue names.
- 5.3: source, linedefined, lastlinedefined, numparams, is_vararg, maxstacksize, code, constants, upvalues (instack, idx), nested functions, lineinfo, locvars, upvalue names. A nested function whose source equals its parent's stores a NULL source.
- 5.4: as 5.3, with a third upvalue byte (
kind); the debug part is lineinfo (n signed byte deltas), abslineinfo (n pairs of pc, line), locvars, upvalue names. - 5.5: linedefined, lastlinedefined, numparams, flag (was is_vararg), maxstacksize, code (count, then zero padding to a multiple of 4 bytes counted from the start of the chunk, then the instructions), constants, upvalues (instack, idx, kind), nested functions, source, lineinfo, abslineinfo (count, padding to 4, raw int pairs), locvars, upvalue names.
Primitive encodings
- 5.1, 5.2: int, size_t, Instruction and lua_Number with the sizes and byte order from the header. A string is a size_t length that counts the trailing NUL, then the bytes with the NUL; length 0 means NULL.
- 5.3: a string is one byte (length + 1; 0 = NULL) or 0xFF followed by a size_t; the NUL is not stored. Counts are native ints.
- 5.4: counts, line numbers and string sizes are variable-length: 7 bits per byte, most significant group first, and the high bit set on the last byte (10 =
8A, 300 =02 AC). A string is varint length+1 (0 = NULL) and the bytes without NUL. lua_Integer and lua_Number constants are raw 8-byte values. - 5.5: the varint is reversed: high bit set on every byte except the last (300 =
82 2C). Integer constants are zigzag-coded varints (x >= 0 as 2x, x < 0 as -2x-1: 1000000 =FA 89 00, -1000000 =FA 88 7F). A string is varint length+1 followed by the bytes with the NUL; a length of 0 is followed by a varint index that reuses the n-th string already written in this chunk (index 0 = NULL), so repeated names and the source name are stored once.
Constants
| Tag | 5.1, 5.2 | 5.3 | 5.4, 5.5 |
|---|---|---|---|
| 0x00 | nil | nil | nil |
| 0x01 | boolean (one more byte) | boolean (one more byte) | false |
| 0x11 | - | - | true |
| 0x03 | number (lua_Number) | float | integer |
| 0x13 | - | integer | float |
| 0x04 | string | short string | short string |
| 0x14 | - | long string | long string |
The tags are the interpreter's type tags (makevariant(t, v) = t | v << 4 in 5.4). 0x03 and 0x13 swap meaning between 5.3 and 5.4.
Instruction encoding
Instructions are 32-bit words in the chunk's byte order.
- 5.1 to 5.3: opcode bits 0-5, A bits 6-13, C bits 14-22, B bits 23-31; Bx = bits 14-31 (unsigned), sBx = Bx - 131071; Ax = bits 6-31 (5.2+, for EXTRAARG). A B or C operand with bit 8 set (>= 256) names constant B-256 (the RK operands).
- 5.4: opcode bits 0-6, A bits 7-14, k bit 15, B bits 16-23, C bits 24-31; Bx = bits 15-31, sBx = Bx - 65535; Ax and sJ = bits 7-31, sJ - 16777215; signed sB/sC are B/C - 127. The
kbit selects a constant operand. - 5.5: as 5.4, plus the ivABC format of NEWTABLE and SETLIST: vB = bits 16-21, vC = bits 22-31.
The operand format of each opcode is in the low bits of luaP_opmodes (5.1-5.3: bits 0-1 = iABC, iABx, iAsBx, iAx; 5.4: bits 0-2 = iABC, iABx, iAsBx, iAx, isJ; 5.5: iABC, ivABC, iABx, iAsBx, iAx, isJ). The opcode numbers of every version are enum facts (Opcodes (Lua 5.x)); 5.5 swapped OP_SHLI and OP_SHRI relative to 5.4.
Loader errors
Tested by loading every version's output with every version's loader (MSVC x64 builds): 5.1 says <name>: bad header in precompiled chunk for any header difference; 5.2 and 5.3 say <name>: version mismatch in precompiled chunk; 5.4 and 5.5 say <name>: bad binary format (version mismatch), and bad binary format (truncated chunk) for a cut-off file. A host that gets these is running a different minor version (or word size) than the chunk was built for.
Decompilers
See Technique:Choosing a decompiler and Tool:Unluac (Lua 5.1 with debug info; forks exist).
Code & repositories
- https://github.com/lua/lua @
8cb93bada561977eb370819e39d7d644e5fd0a3f· license: MIT (declared: the detector found none; check the repository)
Official development repository of the Lua reference implementation (PUC-Rio), with release tags v1.0 to v5.5.1 for diffing any version found in a binary. Note: it has no luac.c (only the lua.org tarballs do).
Tested on: Read at master 8cb93ba and at every 5.x release tag; tags v5.1 to v5.5.1 built with MSVC 14.44 x64 (/O2) plus a self-written lua_dump driver; MIT license text at the end of lua.h (no LICENSE file in the repository). · checked 2026-10-17; last activity 2026-10-16
Pitfalls
- 5.1 and 5.2 compare the whole header, including sizeof(size_t): a chunk written by a 32-bit luac (size_t = 4) does not load into a stock 64-bit interpreter. VLC media player 3.0.23 for Windows x64 ships its scripts (lua/**/*.luac, 36 files) as 5.1 chunks with size_t = 4, which a stock 5.1 x64 build rejects with
bad header in precompiled chunk; VLC's Lua is therefore built with a changed loader or dumper. Unverified which (VLC's contrib patches were not read). - The 5.4 and 5.5 varints use opposite continuation conventions; a 5.4 parser fed 5.5 data does not fail early, it misreads lengths.
- The meaning of constant tags 0x03 and 0x13 differs between 5.3 and 5.4/5.5.
lua_dumpin 5.1 and 5.2 has no strip argument (always full debug info); onlyluac -sstrips there.- Not covered: Lua 5.0 (version byte 0x50 with no format byte; then endianness, sizeof int/size_t/Instruction, the bit widths SIZE_OP/A/B/C, sizeof(lua_Number) and a test number), LuaJIT and Luau bytecode.
Open questions
- Which games or engines ship modified Lua bytecode (renumbered opcodes, changed header, encrypted chunks), and how is each variant recognised? — The page documents only the official format 0 of PUC-Rio Lua 5.1-5.5, verified on self-built chunks and VLC 3.0.23's scripts. Modified variants are commonly mentioned but none was examined here; a format byte other than 0, an opcode table that no longer matches the luaP_opmodes signature, or an unex (asked by PatientStepper99, 2026-10-17)
Evidence & references
- ldump.c, lundump.c, lundump.h, lopcodes.h and lobject.h of https://github.com/lua/lua at tags v5.0, v5.1.1, v5.2.3, v5.3.6, v5.4.8, v5.5.0 and v5.5.1 (commits in the facts).
- Test chunks made from self-written scripts with every release from 5.1 to 5.5.1 (MSVC 14.44 x64), both full and stripped, parsed byte-exact by luacinfo.py; the 36 VLC 3.0.23 chunks also parse byte-exact.