Universal Binary JSON draft-12 serializer for Python
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
src Add object_hook parameter to decoder Nov 27, 2017
test Relax floating point type test case (for 32-bit targets) Aug 1, 2018
ubjson Relax floating point type test case (for 32-bit targets) Aug 1, 2018
.gitignore Make package PyPi-ready Jan 25, 2016
CHANGELOG Version bump for release (0.12.0) Aug 3, 2018
CONTRIBUTING.md Small changes to CONTRIBUTING.md Feb 12, 2016
MANIFEST.in Updated manifest for new source layout Feb 5, 2017
NOTICE C-Extension written from scratch Feb 5, 2017
README.md README spelling correction Jun 13, 2017
UBJSON-Specification.md Limited No-Op support (decoder only) #4 Jun 13, 2017
coverage_test.sh C-Extension written from scratch Feb 5, 2017
ez_setup.py Make package PyPi-ready Jan 25, 2016
pylint.rc Add default param to encoder Nov 24, 2017
setup.py Added Python 3.7 as supported version Aug 1, 2018



This is a Python v3.2+ (and 2.7+) Universal Binary JSON encoder/decoder based on the draft-12 specification.

Installing / packaging

# To get from PyPI
pip3 install py-ubjson

# To only build extension modules inline (e.g. in repository)
python3 setup.py build_ext -i

# To build & install globally
python3 setup.py install

# To skip building of extensions when installing (or building)
PYUBJSON_NO_EXTENSION=1 python3 setup.py install


  • The extension module is not required but provide a significant speed boost.
  • The above can also be run with v2.7+
  • This module is also available via Anaconda (conda-forge)
  • PyPI releases are signed with the Iotic Labs Software release signing key
  • At run time, one can check whether compiled version is in use via the ubjson.EXTENSION_ENABLED boolean


It's meant to behave very much like Python's built-in JSON module, e.g.:

import ubjson

encoded = ubjson.dumpb({u'a': 1})

decoded = ubjson.loadb(encoded)

Note: Only unicode strings in Python 2 will be encoded as strings, plain str will be encoded as a byte array.


import ubsjon

Command-line utility

This converts between JSON and UBJSON formats:

python3 -mubjson
USAGE: ubjson (fromjson|tojson) (INFILE|-) [OUTFILE]



This library has been checked using flake8 and pylint, using a modified configuration - see pylint.rc and flake8.cfg.



Note: This requires coverage.


  • The No-Op type is only supported by the decoder. (This should arguably be a protocol-level rather than serialisation-level option.) Specifically, it is only allowed to occur at the start or between elements of a container and only inside un-typed containers. (In a typed container it is impossible to tell the difference between an encoded element and a No-Op.)
  • Strongly-typed containers are only supported by the decoder (apart from for bytes/bytearray) and not for No-Op.
  • Encoder/decoder extensions are not supported at this time.


The only existing implementation I was aware of at the time of writing (simpleubjson) had the following limitations:

  • Does not support efficient binary encoding
  • Only supports draft-9
  • Only supports individual Python types rather than anything implementing an interface (e.g. Mapping)
  • Does not decode nested arrays or objects in expected form
  • Lacks C extension speed-up