Binary serialisation for Haskell values using lazy ByteStrings

Version on this page:
LTS Haskell 22.26:
Stackage Nightly 2024-06-22:
Latest on Hackage:

See all snapshots binary appears in

BSD-3-Clause licensed by Lennart Kolmodin
Maintained by Lennart Kolmodin, Don Stewart
This version can be pinned in stack with:binary-,5445

binary package

Build Status

Efficient, pure binary serialisation using lazy ByteStrings.

The binary package provides Data.Binary, containing the Binary class, and associated methods, for serialising values to and from lazy ByteStrings. A key feature of binary is that the interface is both pure, and efficient. The binary package is portable to GHC and Hugs.

Installing binary from Hackage

binary is part of The Glasgow Haskell Compiler (GHC) and therefore if you have either GHC or The Haskell Platform installed, you already have binary.

More recent versions of binary than you might have installed may be available. You can use cabal-install to install a later version from Hackage.

$ cabal update
$ cabal install binary

Building binary

binary comes with both a test suite and a set of benchmarks. While developing, you probably want to enable both. Here’s how to get the latest version of the repository, configure and build.

$ git clone [email protected]:kolmodin/binary.git
$ cd binary
$ cabal update
$ cabal configure --enable-tests --enable-benchmarks
$ cabal build

Run the test suite.

$ cabal test

Using binary


import Data.Binary

and then write an instance of Binary for the type you wish to serialise. An example doing exactly this can be found in the Data.Binary module. You can also use the Data.Binary.Builder module to efficiently build lazy bytestrings using the Builder monoid. Or, alternatively, the Data.Binary.Get and Data.Binary.Put to serialize/deserialize using the Get and Put monads.

More information in the haddock documentation.

Deriving binary instances using GHC’s Generic

Beginning with GHC 7.2, it is possible to use binary serialization without writing any instance boilerplate code.

{-# LANGUAGE DeriveGeneric #-}

import Data.Binary
import GHC.Generics (Generic)

data Foo = Foo deriving (Generic)

-- GHC will automatically fill out the instance
instance Binary Foo


  • Lennart Kolmodin
  • Duncan Coutts
  • Don Stewart
  • Spencer Janssen
  • David Himmelstrup
  • Björn Bringert
  • Ross Paterson
  • Einar Karttunen
  • John Meacham
  • Ulf Norell
  • Tomasz Zielonka
  • Stefan Karrmann
  • Bryan O’Sullivan
  • Bas van Dijk
  • Florian Weimer

For a full list of contributors, see here.




  • Replace binary’s home grown Builder with Data.ByteString.Builder. Data.Binary.Builder now exports Data.ByteString.Builder.Builder.
  • Add putList :: [a] -> Put to the Binary class. This is used to be able to use the list writing primitives of the new Builder. This brought a number of speedups; Encoding a String is now 70% faster. [Word8] is 76% faster, which also makes Integer 34% faster. Similar numbers for all [IntXX] and [WordXX].
  • Fail gracefully within Get when decoding Bool and Ordering. Previously when decoding invalid data these instances would fail with error.
  • Add Binary instance for Complex a.
  • Add Monoid and Semigroup instance for Put.


  • Fix compilation error when using older GHC versions and clang. clang barfs on some of its CPP input (#105).


  • When using GHC >= 8, Data.Binary.Get.Get implements MonadFail and delegates its fail to


  • Add binary instance for Data.ByteString.Short.
  • Add get/put functions for all Int sizes to Data.Binary.Builder, Data.Binary.Get and Data.Binary.Put.


  • Address compiler warnings.


  • Added binary instance for Version from Data.Version.
  • Added binary instance for Void from GHC 7.10.1.
  • Added binary instance for (Data.Fixed a) from GHC 7.8.1.
  • Added semigroup instance for Data.Binary.Builder from GHC 8.0.


  • Fix compilation for GHC == 7.2.*.


  • Added binary instance for GHC.Fingerprint (from GHC >= 7.4).



  • Some invalid UTF-8 strings caused an exception when decoded. Those errors will now now fail in the Get monad instead. See #70. Patch contributed by @ttuegel.


  • Add Binary instance for Natural (only with base > 4.8).





  • Add isolate :: Int -> Get a -> Get a.
  • Add label :: String -> Get a -> Get a.


  • Add lookAheadE :: Get (Either a b) -> Get (Either a b).
  • Add MonadPlus instance for Get.


  • Updates to documentation.


  • Add lookAhead :: Get a -> Get a.
  • Add lookAheadM :: Get (Maybe a) -> Get (Maybe a).
  • Add Alternative instance for Get (provides <|>).
  • Add decodeOrFail :: Binary a => L.ByteString -> Either (L.ByteString, ByteOffset, String) (L.ByteString, ByteOffset, a)
  • Add decodeFileOrFail :: Binary a => FilePath -> IO (Either (ByteOffset, String) a).
  • Remove Ord class constraint from Set and Map Binary instances.


  • Add runGetOrFail :: Get a -> L.ByteString -> Either (L.ByteString, ByteOffset, String) (L.ByteString, ByteOffset, a).


  • Documentation tweeks, internal restructuring, more tests.


  • some and many more efficient.
  • Fix bug where bytesRead returned the wrong value.
  • Documentation improvements.


  • Fix bug where a decoder could return with Partial after the previous reply was Nothing.