Format:LuaJIT bytecode
| Developer | Mike Pall |
|---|---|
| Versions | dump version 1 (LuaJIT 2.0), 2 (LuaJIT 2.1); 0x80 or higher for private modifications |
| Magic | 1B 4C 4A + version byte (2 in 2.1) + flags (ULEB128) |
| Extensions | .ljbc, .luac, .raw (luajit -b output name is chosen by the user) |
| Endianness | instructions and constants in the dump follow flag bit 0 (BE) |
| License | MIT (reference implementation) |
| On this wiki | Facts · Code · Notes · Topics |
Precompiled chunk format of LuaJIT (luajit -b, string.dump): the header 1B 4C 4A (ESC 'L' 'J'), a dump version byte (1 for LuaJIT 2.0, 2 for 2.1), a ULEB128 flags value and an optional chunk name, then length-prefixed function prototypes with 32-bit instructions in an 8-bit-opcode ABC/AD encoding and ULEB128-packed constants. It is unrelated to the PUC-Rio layout of Format:Lua bytecode.
Overview
Library:LuaJIT has its own bytecode, with a different instruction set from PUC-Rio Library:Lua 5.1 even though the language is the same: luajit -b script.lua out.raw, string.dump(f [, strip]) and lj_bcwrite produce it, lj_bcread loads it (the loader accepts a chunk whose first byte is 0x1B). A tool for Format:Lua bytecode cannot read it. The format has no checksum.
Header
Grammar from the comment in src/lj_bcdump.h:
dump = header proto+ 0U
header = ESC 'L' 'J' versionB flagsU [namelenU nameB*]
proto = lengthU pdata
pdata = phead bcinsW* uvdataH* kgc* knum* [debugB*]
phead = flagsB numparamsB framesizeB numuvB numkgcU numknU numbcU [debuglenU [firstlineU numlineU]]
(B = 8 bit, H = 16 bit, W = 32 bit, U = ULEB128; the last proto is followed by a 0 length)
Bytes: 1B 4C 4A, the dump version (BCDUMP_VERSION = 2 in the 2.1 source; a private modification of the format must use 0x80 or higher, so a first-byte-after-LJ of 0x80+ means a vendor fork), the flags (ULEB128; one byte for the known bits) and, unless the dump is stripped, the ULEB128 length and bytes of the chunk name (for example @script.lua). A stripped dump has no name and no debug sections.
Flags: 0x01 big-endian, 0x02 stripped, 0x04 uses FFI, 0x08 FR2 (64-bit stack frames, GC64 builds), 0x10 uses bit ops; 0x80000000 asks the writer for deterministic table order. The reader rejects a dump whose version differs, that has unknown flag bits, or whose FR2 flag does not match the loading VM's frame size: a GC64 LuaJIT cannot load non-GC64 dumps and vice versa. Typical headers: 1B 4C 4A 02 00 (2.1, full), 1B 4C 4A 02 02 (2.1 stripped), 1B 4C 4A 02 0A (2.1 stripped, GC64 build), 1B 4C 4A 01 .. (2.0).
Instructions
Instructions are 32-bit words with an 8-bit opcode in the low byte: format ABC = op | A<<8 | C<<16 | B<<24, format AD = op | A<<8 | D<<16 (D 16 bit; jumps use D - 0x8000). Constants are split in GC constants (child prototype type 0, table 1, signed int64 2, uint64 3, complex 4, strings as 5 + length) and numeric constants (ULEB128 of value+1 for ints that fit 32 bit, else two words). Table constants carry nil/false/true/int/num/str entries (types 0 to 5). Slot numbering in the dump is the in-memory numbering, so a decompiler must know the exact VM version (the opcode list in src/lj_bc.h changes between 2.0 and 2.1 and in the rolling branch).
Decompilers
See Technique:Choosing a decompiler (the LuaJIT decompiler row is marked Unverified there).
Code & repositories
- https://github.com/LuaJIT/LuaJIT @
2a8e017ef1ece6a95b983ffca073d30609dce7c4· license: MIT (declared by the contributor; GitHub's detector did not recognize a license file)
The LuaJIT source (MIT): src/lj_bcdump.h documents the dump format, lj_bc.h the instruction set, lj_bcwrite.c and lj_bcread.c the writer and loader; the v2.1 branch is the rolling release.
Tested on: source read, not run: source read at the pinned commit; nothing built or run · checked 2026-10-18; last activity 2026-10-14
Pitfalls
- Many Lua games ship LuaJIT bytecode with the
.luaor.luacextension; check the third byte (4A= LuaJIT,75= PUC-Rio). - LuaJIT 2.0 (branch v2.0 at commit 2410b57fd466298e6a64a68986a6b696c23656ac) defines BCDUMP_VERSION 1 and only the flags BE 0x01, STRIP 0x02 and FFI 0x04 (known mask 0x07), in src/lj_bcdump.h lines 39-46; 2.1 (branch v2.1, commit dd3b24369ddfaa83c78cd6fdd91d157c8968ec8d) defines version 2 and adds FR2 0x08, BITOP 0x10 and DETERMINISTIC 0x80000000 (lines 39-50). Read from the source; no 2.0 binary was checked.
- Obfuscated or modified dumps (renumbered opcodes, XOR-ed bytes) are common; the 0x80+ version rule is a convention, not enforced.
Evidence & references
- LuaJIT/LuaJIT commit 2a8e017ef1ece6a95b983ffca073d30609dce7c4:
src/lj_bcdump.h(grammar,BCDUMP_*constants),src/lj_bcwrite.c(bcwrite_header, lines 388-410),src/lj_bcread.c(header validation, lines 398-413),src/lj_bc.h(instruction formats). Read only, nothing built.