ChunkSpy: A Lua 5 Binary Chunk Disassembler


LuaForge Project Page:

ChunkSpy is a tool to disassemble a Lua 5 binary chunk into a verbose listing that can then be studied. Its output bears a resemblance to the output listing of assemblers. I wanted something that can tell me in great detail what goes on inside a Lua binary chunk file, not just the instructions. It is intended to be a tool for learning Lua internals as well.

ChunkSpy is contained in a single Lua file, ChunkSpy.lua, so that it is very portable and very customizable; there are no C source files to compile. All you need is a copy of the Lua command line executable, lua, plus optionally the binary chunk compiler, luac, to generate those binary chunk files.

I have also written a brief guide to all Lua 5 virtual machine instructions, for those who need such things: A No-Frills Introduction to Lua 5.1 VM Instructions (available for version 5.0.2 and version 5.1; please follow the document links on the page for the PDF and ODT files.) ChunkBake is a Lua 5 assembler which complements ChunkSpy.

If you want to disassemble to source code, try LuaDec by Hisham Muhammad.


ChunkSpy can do the following:

This is a beta release, so it is NOT bug-free. Everything was done on self-compiled Lua 5.0.2 and Lua 5.1 executables, on Win32. Bug reports are welcome, as are enhancements. Please see the README in the release for more information on its features and limitations. Feedback and contributions are welcome.


You can get all the ChunkSpy files at LuaForge:

Latest version: ChunkSpy 0.9.8 (66KB zip) is the Lua version.
Win32 binary (143KB zip) available for version 0.9.7 at the moment.


2006-03-13: ChunkSpy 0.9.8. Complete support for Lua 5.1.
2006-03-13: Added A No-Frills Introduction to Lua 5.1 VM Instructions (in ODT or PDF)
2006-02-21: Updated A No-Frills Introduction to Lua 5 VM Instructions (in ODT or PDF)
2005-06-05: ChunkSpy 0.9.7. Experimental support for Lua 5.1wk6.
2005-03-25: ChunkSpy 0.9.6. Fixed OP_NEWTABLE decoding for Lua 5.1wk5 disassembler.
2005-03-03: ChunkSpy 0.9.5. Experimental support for Lua 5.1wk4. Upcoming Lua 5.1 support will be in the form of a separate script.
Added A No-Frills Introduction to Lua 5 VM Instructions (in SXW or PDF), available from the Document Manager tab in ChunkSpy's LuaForge Project Page.
2004-11-21: ChunkSpy 0.9.4.
Added comments for some instructions, and a Win32 stand-alone binary.
2004-11-14: ChunkSpy 0.9.3.
Added binary chunk rewriting (--rewrite "plat") option, and non-native binary chunk load and execute (--run) option.
2004-11-09: ChunkSpy 0.9.2.
Added interactive mode (--interact), brief listings (--brief), output file specification (-o <file>), and source to listing mode (--source <file>).
2004-11-07: ChunkSpy 0.9.1.
Basic features, initial release on LuaForge.


Thanks to the LuaForge team for hosting this material. This page was written on SeaMonkey. ChunkBake was developed using the SciTE editor.

This page Copyright © 2003-2006 KHMan. See the script for license information (MIT-style). Last Revised: 2006-11-04.
Canonical URL: