A fast, robust, secure, richly-featured table serialisation library for Lua
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Since 2016-02-16, Smallfolk is deprecated. I will still fix reported bugs, but for new projects, I recommend bitser if you're using LuaJIT, and binser otherwise.


Smallfolk is a reasonably fast, robust, richtly-featured table serialization library for Lua. It was specifically written to allow complex data structures to be loaded from unsafe sources for LÖVE games, but can be used anywhere.

You use, distribute and extend Smallfolk under the terms of the MIT license.


Smallfolk is very simple and easy to use:

local smallfolk = require 'smallfolk'

print(smallfolk.dumps({"Hello", world = true}))
-- prints:
-- {"Hello","world":t}
-- bar


Using Serpent's benchmark code, Smallfolk's serialization speed is comparable to that of Ser (and Ser is 33% faster than Serpent).

It should be noted that deserialization is much slower in Smallfolk than in most other serialization libraries, because it parses the input itself instead of handing it over to Lua. However, if you use LuaJIT this difference is much less, and it is not noticable for small outputs. By default, Smallfolk rejects inputs that are too large, to prevent DOS attacks.


Sometimes you have strange, non-euclidean geometries in your table constructions. It happens, I don't judge. Smallfolk can deal with that, where some other serialization libraries (or anything that produces JSON) cry "Iä! Iä! Cthulhu fhtagn!" and give up — or worse, silently produce incorrect data.

local smallfolk = require 'smallfolk'

local cthulhu = {{}, {}, {}}
cthulhu.fhtagn = cthulhu
cthulhu[1][cthulhu[2]] = cthulhu[3]
cthulhu[2][cthulhu[1]] = cthulhu[2]
cthulhu[3][cthulhu[3]] = cthulhu
-- prints:
-- {{{@2:@3}:{@4:@1}},@3,@4,"fhtagn":@1}


Smallfolk doesn't run arbitrary Lua code, so you can safely use it when you want to read data from an untrusted source.


Smallfolk creates really small output files compared to something like Ser when it encounters a lot of non-tree-like data, by using numbered references rather than item assignment.


Check out tests.lua to see how Smallfolk behaves with all kinds of inputs.



Returns an 8-bit string representation of object. Throws an error if object contains any types that cannot be serialised (userdata, functions and threads).

###smallfolk.loads(string[, maxsize=10000])

Returns an object whose representation would be string. If the length of string is larger than maxsize, no deserialization is attempted and instead an error is thrown. If string is not a valid representation of any object, an error is thrown.

See also

  • Ser: for trusted-source serialization
  • Lady: for trusted-source savegames