gopher-lua embeds a Lua 5.1 VM in Go and trades the C stack API for Go ergonomics
GopherLua: VM and compiler for Lua in Go
At a glance
- What is it?
- GopherLua is a Lua 5.1 virtual machine and compiler written in Go, built for embedding a scripting language into a Go host program. Its central design decision is that the stack carries arguments and return values only.
- Who is it for?
- Adopt GopherLua when the host program is written in Go, the scripts are Lua 5.1, and the people writing them are Go developers who will value DoString and type assertions over the raw stack. Do not adopt it for Go host code that needs metatable dispatch through the public fields of LTable and similar objects, for scripts that need Lua 5.2 features beyond the goto statement, or on anything approaching the performance of the C implementation.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- yuin/gopher-lua7,009 ★ · +29
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| yuin/gopher-lua | 7k | 7k |
29 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The stack carries arguments and return values, and nothing else
The stated goal is to be a scripting language with extensible semantics, with the same goal as Lua itself, so that a Go program can hand behaviour to users at runtime. What differs from stock Lua is the shape of the API. The project is explicit that its APIs perform in much the same way as Lua, but the stack is used only for passing arguments and receiving returned values. A stack based API like the one in the original implementation would cut memory allocations and the conversions between concrete types and interfaces, and that would make GopherLua faster. The project gives this performance up on purpose, preferring the user-friendliness of the Go shaped interface.
That is a real trade rather than an oversight, and it has a consequence worth planning around: anything a script does at the boundary between Go and Lua moves through Go values rather than through C stack slots, so the cost profile of a hot loop differs from what the same loop costs under the C VM.
Channel operations are supported, and the documentation has a Goroutines section covering them. The data model even lists LChannel as a value type backed by a Go channel, with the type constant LTChannel. Go channels are therefore part of the value system rather than something bolted on through a userdata wrapper.
Every value is an LValue, and LBool cannot be type asserted the way you expect
All data in a GopherLua program is an LValue, an interface with two methods, String() string and Type() LValueType. The type table is short and worth reading carefully, because the Go types behind the names are not uniform. LNilType and LBool are constants with no Go type of their own. LNumber is float64, LString is string, and LFunction, LUserData and LTable are struct pointers. LState is a struct pointer that reports LTThread, and LChannel is a Go channel that reports LTChannel.
You check a type either by Go type assertion or by comparing the Type() result:
lv := L.Get(-1) // get the value at the top of the stack
if str, ok := lv.(lua.LString); ok {
// lv is LString
fmt.Println(string(str))
}
if lv.Type() != lua.LTString {
panic("string required.")
}The trap is that LBool, LNumber and LString are not pointers, so the usual pointer unwrap does not exist. To test LNilType and LBool you must use the pre-defined constants, and the documentation marks the assertion form as wrong:
if lv == lua.LTrue { // correct
}
if bl, ok := lv.(lua.LBool); ok && bool(bl) { // wrong
}Lua's rule that both nil and false make a condition false is available through LVIsFalse and LVAsBool, so host code does not have to reimplement it.
A registry set too small ends in a panic and never shrinks back
The registry of an LState is the stack storage used for calling functions, both Lua and Go, and for the temporary variables of expressions. Its storage needs grow with callstack usage and with how complex the code is. Three options on lua.Options control it:
L := lua.NewState(lua.Options{
RegistrySize: 1024 * 20, // this is the initial size of the registry
RegistryMaxSize: 1024 * 80, // this is the maximum size that the registry can grow to. If set to `0` (the default) then the registry will not auto grow
RegistryGrowStep: 32, // this is how much to step up the registry by each time it runs out of space. The default is `32`.
})
defer L.Close()Read that default carefully. RegistryMaxSize of 0 means the registry does not auto grow at all, so a script that needs more space than the initial RegistrySize will end in a panic. Two failure modes sit either side of that: too small for the script and the process panics, too large and you waste memory, which adds up quickly when a program instantiates many LStates. Auto growth costs a small performance hit at the moment of resizing and nothing after that.
The direction of growth is one way. Once the registry has grown it will not shrink again, so an LState keeps its high water mark for as long as it lives. The documentation suggests tuning these values when a process holds a large number of LStates.
Callstack depth counts Lua frames only, and fixed sizing is the faster mode
The size of an LState's callstack is what limits the maximum call depth for Lua functions inside a script. Go function calls do not count toward it, which means recursion through the host into Go and back into Lua can go deeper than the configured depth suggests. A script that recurses through a Go callback is the case to test, not a script that recurses purely inside Lua.
The callstack runs in one of two modes. Fixed is described as having the highest performance and a fixed memory overhead, which means the memory is reserved whether or not the script uses it. Auto sizing allocates and releases callstack pages on demand, keeping the minimum amount of memory in use at any time, and pays a small performance cost every time a new page of callframes is allocated.
Both the callstack and the registry can be set to a fixed size or to auto size, independently. For a single long-lived LState that runs one known script, fixed sizing is the cheaper choice at runtime. For a service that creates an LState per request and runs small scripts, auto sizing wastes less between requests, and the per page cost may never be reached often enough to matter. The documentation says tuning is worth the effort when many LStates exist in one process.
Metatables and error handling stop where the values become Go structs
LFunction, LUserData and LTable are struct pointers with public methods and fields, and the documentation invites you to use those directly for performance and debugging instead of going back through the VM. Two limitations come with that invitation, and they are listed plainly: metatable does not work, and there is no error handling.
The first one bites in the middle of ordinary Lua idioms. A table with a metatable that redirects __index, __newindex or __call is how a lot of Lua code builds objects, and a host that hands a Go backed LTable to a script cannot expect that dispatch to fire through the public fields. The second one is about the host side: reaching into a public field is a direct Go access, and the README lists no error handling for it.
Neither limitation is subtle once you know it, but both are easy to miss if you arrive from the C API, where every table is an opaque pointer and every failure is a value on the stack. Host code that reaches into these public fields and expects metatables or error handling to apply needs checking before it runs here.
go get, then NewState and either DoString or DoFile
Installation is a single module fetch. The package path is the repository path:
go get github.com/yuin/gopher-luaIn a host program you import the package, create a state, and run a script string or a file. Both entry points return an error, and the documented example panics on failure:
L := lua.NewState()
defer L.Close()
if err := L.DoString(`print("hello")`); err != nil {
panic(err)
}For a script on disk, swap the call and the file name:
L := lua.NewState()
defer L.Close()
if err := L.DoFile("hello.lua"); err != nil {
panic(err)
}Two details from that snippet matter in production. The state is closed with defer, so the host owns the lifetime. And the returned error is an ordinary Go error, which means the host decides whether a syntax error in a user script crashes the process or becomes a message in a UI. The defer runs before the caller can act on a panic, so Close happens either way.
For reading the rest of the API, the project points at the Lua Reference Manual and the Go documentation, and notes that anything not commented in the Go documentation behaves as the reference manual describes, except that GopherLua uses objects where Lua uses stack indices.
Go 1.23, a generated source step, and the lua5.1 conformance suite
The module declares Go 1.23 and one direct dependency, github.com/chzyer/readline. Everything else in go.mod is indirect.
The Makefile has three targets, and each one runs a code generation step before compiling:
./_tools/go-inline *.go && go fmt . && go build
./_tools/go-inline *.go && go fmt . && go build cmd/glua/glua.go
./_tools/go-inline *.go && go fmt . && go testThe _tools directory holds the go-inline tool these targets run over the Go sources. The glua target builds the standalone interpreter in cmd/glua.
Two test trees are visible in the repository layout: _lua5.1-tests and _glua-tests. The first is the Lua 5.1 conformance suite, the second is the project's own tests, which is how a Lua implementation that aims at compatibility gets told when it has drifted.
On status, the project is not archived, the licence is MIT, and the release history is thin and dated: v1.1.0 on 2023-01-22, v1.1.1 on 2023-12-03, and v1.1.2 on 2026-04-01, which is also the date of the last push. Between those two earlier tags and the most recent one there is a gap of more than two years, so pin a version in a production dependency rather than tracking the default branch.
Editorial conclusion
Adopt GopherLua when the host program is written in Go, the scripts are Lua 5.1, and the people writing them are Go developers who will value DoString and type assertions over the raw stack. Do not adopt it for Go host code that needs metatable dispatch through the public fields of LTable and similar objects, for scripts that need Lua 5.2 features beyond the goto statement, or on anything approaching the performance of the C implementation. Before committing, size the registry and callstack explicitly rather than leaving the defaults, then load one representative script and watch whether memory grows as the registry auto-grows, because it never shrinks again.
Frequently asked questions
How do I embed Lua in a Go program with gopher-lua?
Fetch the module with go get github.com/yuin/gopher-lua, create a state with lua.NewState(), defer L.Close(), and run a script with L.DoString or L.DoFile. Both return an error, so the host decides whether a script failure is fatal.
How do I check whether a gopher-lua value is a boolean?
Use the pre-defined constants rather than a type assertion, because LBool is a constant rather than a pointer. Comparing against lua.LTrue is the correct form; the documentation marks the assertion with a bool conversion as wrong. LVIsFalse and LVAsBool implement the Lua rule that nil and false are both false.
Why does my gopher-lua script panic when the registry is too small?
A registry that is too small for the script ends in a panic. RegistryMaxSize defaults to 0, which means the registry does not auto grow, so you either size RegistrySize for the worst case or set RegistryMaxSize and leave RegistryGrowStep at its default of 32.
Does gopher-lua support metatables?
Metatable does not work for the Go backed objects LFunction, LUserData and LTable when you use their public methods and fields directly, and the documentation lists that alongside a lack of error handling as the two limitations of that approach.
Which Lua versions does gopher-lua implement?
It is a Lua 5.1 virtual machine and compiler, with the goto statement from Lua 5.2 added on top. Everything not commented in the Go documentation behaves as the Lua Reference Manual describes.
Is gopher-lua fast?
The project states plainly that GopherLua is not fast but not too slow, and reports performance almost equivalent to or a little better than Python 3 on micro benchmarks, with benchmark results on the project wiki. It also gives up the faster stack based API on purpose, preferring user-friendliness.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/yuin-gopher-lua)Star history chart for your README
[](https://hysenlabs.com/projects/yuin-gopher-lua)Was this useful?