'bdec', tools for decoding binary files.


Manually writing decoders for binary formats is a time consuming, frustrating, and costly process; it is also the source of many bugs.

Using bdec, developers can write specifications for binary formats using simple low-level constructs that combine in powerful ways, allowing many binary formats to be partially (and often fully) specified. From this specification, bdec will generate source code for decoders and encoders.

While other high level specification languages exist (such as ASN.1, or Google protocol buffers), few existing formats make use of these languages, and such specification languages cannot usually be retro-fitted to existing binary formats.

With bdec;

Getting started

  1. Download the latest version.
  2. Go through the tutorial.
  3. Try writing a specification for your own file formats, referring to the documentation where necessary (pdf documentation is also available).


The easiest way to install bdec is to use python's easy_install application. Run:

easy_install bdec

to install the latest version of the bdec decoder and compiler.

See the CHANGELOG for past releases.


Any comments or questions can go to the group mailing list at This is a moderated list, so please be patient if your question doesn't show up immediately.



The bdec library and code generated by the specification compiler are made available under the GNU Lesser General Public License (LGPL). In summary, this means;

  • The software can be used free of charge in any application (including closed source applications).
  • If you distribute an application using either the bdec library or code generated by the bdec library, the binary containing this code must be dynamically linked (eg: .dll in Windows, .so in Linux).
  • The source code to this dynamic library must be made available to anyone you distribute the library to.

See COPYRIGHT and LICENSE for detailed copyright information.


The source control tree is available on github at

git clone

Dependencies that must be installed are pyparsing and mako.

Similar projects

Some other tools that perform 'generic' binary decoding include;

Projects that generate decoders from high level specifications;