pack( data )

Serialize a data.

unpack( str )

Deserialize a string.

unpacker( src )

Accept a string or a ltn12.source and returns a iterator.

The iterator gives a couple of values, the interesting value is the second.

set_number( str )

Configures the behaviour of pack. The valid options are 'double' and 'float'. The default is usually 'double'.

set_integer( str ) DEPRECATED

Configures the behaviour of pack. The valid options are 'signed' and 'unsigned'. The default is 'unsigned'.

set_array( str )

Configures the behaviour of pack. The valid options are 'without_hole', 'with_hole' and 'always_as_map'. The default is 'without_hole'.

set_string( str )

Configures the behaviour of pack. The valid options are 'string', 'string_compat' and 'binary'. The default is 'string_compat' in order to be compatible with old implementation.

Data Conversion

  • The following Lua types could be converted : nil, boolean, number, string and table.
  • A Lua number is converted into an MessagePack integer if math.floor(num) == num, otherwise it is converted into the MessagePack float or double (see set_number).
  • When a MessagePack 64 bits integer is converted to a Lua number it is possible that the resulting number will not represent the original number but just an approximation.
  • A Lua table is converted into a MessagePack array only if all the keys are composed of strictly positive integers, without hole or with holes (see set_array). Otherwise it is converted into MessagePack map.
  • An empty table is always converted into a MessagePack array.
  • With set_array'always_as_map', all Lua table are converted into a MessagePack map.
  • Lua does not allow nil and NaN (0/0) as table index, by default, the deserialization of this kind of MessagePack map skips the key/value pair. The value could preserved by defining the module member sentinel which is used as key.
  • LIMITATION : MessagePack cannot handle data with cyclic reference.


There are introduced with MessagePack specification v5.

During deserialization, unknown extensions are skipped and evaluated as a Lua nil.

The following example shows how to create a new module which extends MessagePack with the serialization/deserialization of Lua function (obviously, the emitter and receiver MUST use the same version of Lua).

local loadstring = loadstring or load
local mp = require 'MessagePack'
local EXT_FUNCTION = 7

mp.packers['function'] = function (buffer, fct)
    mp.packers['ext'](buffer, EXT_FUNCTION, assert(string.dump(fct)))

mp.build_ext = function (tag, data)
    if tag == EXT_FUNCTION then
        return assert(loadstring(data))

return mp

Advanced usages

The following Lua hack allows to have several instances of the module MessagePack, each one with its own settings.

local mp1 = require 'MessagePack'
package.loaded['MessagePack'] = nil     -- the hack is here
local mp2 = require 'MessagePack'


When global settings are not enough, the following recipe allows to use a specific encoding for only a part of a data structure.

local mp = require 'MessagePack'
mp.packers['function'] = function (buffer, fct)

local function BINARY (str)
    return function (buffer)
        mp.packers['binary'](buffer, str)

local function FLOAT (n)
    return function (buffer)
        mp.packers['float'](buffer, n)

mp.pack { 'encoded_with_global_settings', BINARY'encoded_as_binary', 42, FLOAT(42) }


Basic usage

local mp = require 'MessagePack'


mpac = mp.pack(data)
data = mp.unpack(mpac)

local ltn12 = require 'ltn12'
src = ltn12.source.file('file', 'r'))
for _, v in mp.unpacker(src) do