Binary serialisation for Haskell values using lazy ByteStrings

Version on this page:
LTS Haskell 10.6:
Stackage Nightly 2018-02-23:
Latest on Hackage:

See all snapshots binary appears in

BSD3 licensed by Lennart Kolmodin
Maintained by Lennart Kolmodin, Don Stewart

binary package

Hackage version Stackage version 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
$ 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.




  • was first released as version It didn't have any breaking changes though, so it was again released as version according to PVP. Next breaking release of binary will be version


  • Add Binary instances for Typeable TypeReps, #131.


  • Fix compilation with bytestring < 0.10.4.


  • binary supports GHC >= 7.4.2
  • Performance improvements for Alternative functions.
  • put/get functions for IEEE-754 floats and doubles, #119.
  • Fix performance bugs, #115.
  • Binary instances for datatypes in Data.Monoid and Data.Semigroup, #114.


  • 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).


  • Fix performance bug that was noticable when you get a big strict ByteString and the input to the decoder consists of many small chunks. - -
  • Fix memory leak when decoding Double and Float.
    • Commit 497a181c083fa9faf7fa3aa64d1d8deb9ac76ecb
  • We now require QuickCheck >= 2.8. Remove our version of arbitrarySizedNatural.


  • 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).


  • Remove INLINEs from GBinary/GSum methods. These interact very badly with the GHC 7.9.x simplifier. See also; - - -


  • Make import of GHC.Base future-proof (


  • Fix to compile on GHC 6.10.4 and older (


  • 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.


comments powered byDisqus