MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON but it's faster and smaller. For example, small integers (like flags or error code) are encoded into a single byte, and typical short strings only require an extra byte in addition to the strings themselves.

If you ever wished to use JSON for convenience (storing an image with metadata) but could not for technical reasons (binary data, size, speed…), MessagePack is a perfect replacement.

require 'msgpack'
msg = [1,2,3].to_msgpack  #=> "\x93\x01\x02\x03"
MessagePack.unpack(msg)   #=> [1,2,3]

Use RubyGems to install:

gem install msgpack

or build msgpack-ruby and install:

gem install --local pkg/msgpack

Use cases


MessagePack for Ruby should run on x86, ARM, PowerPC, SPARC and other CPU architectures.

And it works with MRI (CRuby) and Rubinius. Patches to improve portability is highly welcomed.

Serializing objects

Use MessagePack.pack or to_msgpack:

require 'msgpack'
msg = MessagePack.pack(obj)  # or
msg = obj.to_msgpack

Streaming serialization

Packer provides advanced API to serialize objects in streaming style:

# serialize a 2-element array [e1, e2]
pk =

See API reference for details.

Deserializing objects

Use MessagePack.unpack:

require 'msgpack'
obj = MessagePack.unpack(msg)

Streaming deserialization

Unpacker provides advanced API to deserialize objects in streaming style:

# deserialize objects from an IO
u =
u.each do |obj|
  # ...

or event-driven style which works well with EventMachine:

# event-driven deserialization
def on_read(data)
  @u ||=
  @u.feed_each(data) {|obj|
     # ...

See API reference for details.

Extension Types

Packer and Unpacker support Extension types of MessagePack.

# register how to serialize custom class at first
pk =
pk.register_type(0x01, MyClass1, :to_msgpack_ext) # equal to pk.register_type(0x01, MyClass)
pk.register_type(0x02, MyClass2){|obj| obj.how_to_serialize() } # blocks also available

# almost same API for unpacker
uk =
uk.register_type(0x01, MyClass1, :from_msgpack_ext)
uk.register_type(0x02){|data| MyClass2.create_from_serialized_data(data) }

MessagePack::Factory is to create packer and unpacker which have same extention types.

factory =
factory.register_type(0x01, MyClass1) # same with next line
factory.register_type(0x01, MyClass1, packer: :to_msgpack_ext, unpacker: :from_msgpack_ext)
pk = factory.packer(options_for_packer)
uk = factory.unpacker(options_for_unpacker)

For MessagePack.pack and MessagePack.unpack, default packer/unpacker refer MessagePack::DefaultFactory. Call MessagePack::DefaultFactory.register_type to enable types process globally.

MessagePack::DefaultFactory.register_type(0x03, MyClass3)
MessagePack.unpack(data_with_ext_typeid_03) #=> MyClass3 instance

Buffer API

MessagePack for Ruby provides a buffer API so that you can read or write data by hand, not via Packer or Unpacker API.

This MessagePack::Buffer is backed with a fixed-length shared memory pool which is very fast for small data (<= 4KB), and has zero-copy capability which significantly affects performance to handle large binary data.

How to build and run tests

Before building msgpack, you need to install bundler and dependencies.

gem install bundler
bundle install

Then, you can run the tasks as follows:

How to build -mingw32 rubygems

MessagePack mingw32/64 rubygems build process uses rake-compiler-dock. Run:

rake build:windows

Once this step successes, target gems exist in pkg/msgpack-*-x86,x64-mingw32.gem.

Updating documents

Online documents ( is generated from gh-pages branch. Following commands update documents in gh-pages branch:

bundle exec rake doc
git checkout gh-pages
cp doc/* ./ -a



Sadayuki Furuhashi <>


Copyright © 2008-2015 Sadayuki Furuhashi


Apache License, Version 2.0