BSD-3-Clause licensed by Michael Snoyman, Anton Ageev, Kirill Simonov
Maintained by Michael Snoyman
This version can be pinned in stack with:yaml-,5178


GitHub build and test status Appveyor build status

Provides support for parsing and emitting Yaml documents.

Data.Yaml provides a high-level interface based around the JSON datatypes provided by the aeson package. It uses Text.Libyaml from libyaml in its implementation of the low-level yaml encoder/decoder.


Usage examples can be found in the Data.Yaml documentation or in the examples directory.

Additional yaml modules

  • Data.Yaml.Include supports adding !include directives to your YAML files.
  • Data.Yaml.Builder and Data.Yaml.Parser allow more fine-grained control of parsing an rendering, as opposed to just using the aeson typeclass and datatype system for parsing and rendering.
  • Data.Yaml.Aeson is currently a re-export of Data.Yaml to explicitly choose to use the aeson-compatible API.


Converters json2yaml and yaml2json can be built by disabling flag no-exe, e.g., one of:

cabal install yaml -f-no-exe
stack install yaml --flag yaml:-no-exe


ChangeLog for yaml

  • Compat with aeson 2.2

  • For optparse-applicative-0.18: use pretty instead of text #216

  • Fix ambiguous occurrence AesonException

  • Undo previous change (breakage with aeson 2)

  • Data.Yaml.Pretty: provide key-sorting function with path to parent object #206

  • Export Parse and StringStyle #204

  • Support aeson 2 #202

  • yaml2json: add --help and --version options #197
  • json2yaml: add --help and --version options #198
  • Add the -o options to both yaml2json and json2yaml #200

  • New functions capable of parsing YAML streams containing multiple documents into a list of results:
    • decodeAllEither'
    • decodeAllFileEither
    • decodeAllFileWithWarnings
    • decodeAllThrow
    • decodeAllFileThrow

  • add ToYaml instance for String #186

  • Don’t wrap up async exceptions #185

  • Reduces some of the code duplication between the encode and encodePretty functions
  • The output of encodePretty has been improved:
    • Multiline strings now use Literal style instead of SingleQuoted
    • Special keys are now quoted in mappings #179
  • Support for complex keys in mappings: #182
    • Adds complexMapping function to Data.Yaml.Builder
    • Decode functions now return a NonStringKey error when attempting to decode a mapping with a complex key as it is not possible to decode these to an Aeson Value
  • Adds missing ToYaml instances

  • Compiles with GHC 8.8.1 (MonadFail split)

  • Use the appropriate Scientific rendering function to avoid a memory overflow when rendering. The previously used function from aeson would not use scientific notation, and could use large amounts of memory for values such as 1e9999999999999.

  • Better error messages in the Data.Yaml.Config module #168
  • Add LoadSettingsException exception and remove error printing from loadYamlSettings #172

  • Split out the libyaml and Text.Libyaml code into its own package. #145

  • Add decodeMarked and decodeFileMarked functions to Text.Libyaml, and extend native bindings to extract mark information. #157

  • Add support for anchors and aliases to Data.Yaml.Builder #155
  • Fix test suite for 32 bit machines #158

  • Add EncodeOptions and FormatOptions to control the style of the encoded YAML. #153
  • Default to using literal style for multiline strings #152

  • Correctly declare libyaml dependency on system-libyaml flag #151


  • Avoid incurring a semigroups dependency on recent GHCs.
  • Fix a space leak that was introduced with 0.10.0 #147


  • Add decodeFileWithWarnings which returns warnings for duplicate fields


  • Expose style and tags on mappings and sequences in Text.Libyaml #141


  • Escape keys as necessary #137
  • Support hexadecimal and octal number values #135
  • More resilient isNumeric (should reduce cases of unneeded quoting)
  • hpackify
  • src subdir


  • Add decodeThrow and decodeFileThrow convenience functions.
  • Upgrade libyaml versions
  • Deprecate decode and decodeEither


  • Removed AppSettings mentioned in loadYamlSettings error message.


  • Deprecated decodeFile #129
  • Turn off executables by default #103


  • Add Data.Yaml.TH.yamlQQ


  • Support conduit 1.3


  • Add Semigroup instance #123

  • Use throwM instead of monadThrow

  • Drop aeson-qq dep (incompatible with Stackage Nightly)


  • Tweaks to the executable yaml2json #119:
    • Add command-line option -h and --help to show help message
    • Error messages are now written to stderr instead of stdout


  • New encodePretty option setConfDropNull to drop null values from objects #116

  • Avoid over-escaping * #113

  • Update libyaml #110

  • Update CPP MIN_VERSION_* checks #109


  • Re-export the with helpers from aeson

  • Make numeric string detection slightly smarter so, e.g., . does not get quoted


  • Update to libyaml hosted on Github #105

  • Fix wrong file not found exception in Data.Yaml.Include with pre- directory #104

  • Add missing test files #102


  • Decode empty inputs as Null #101


  • Upgrade to libyaml 0.1.7

  • Add Data.Yaml.TH module

  • Add O_TRUNC when opening files

  • s/fdopen/_fdopen on Windows #96

  • Properly fix previous bug (fixes #94)

  • Remove file with non-ASCII name due to Stack/cabal-install/Hackage restrictions (see #92)

  • Handle non-ASCII filenames correctly on Windows #91

  • Improve prettyPrintParseException when context is empty #89


  • Switched yaml decode function for config file readers in Data.Yaml.Config to the one from Data.Yaml.Include that supports !include syntax.

  • Fix pretty-printing order of UnexpectedEvent’s fields (fixes #84) #85

  • Avoid bug in Cabal #83


  • loadYamlSettingsArgs

  • Slight doc improvement


Add env variable parsing. loadYamlSettings can read config values from the environment with Yaml that specifies an env var. The syntax is

var: _env:ENV_VAR:default

  • Give a warning when compiling with GHCJS

  • Canonicalise Monad instances #76

  • Compile with aeson below 0.7 #70


  • Parse Scientific directly, avoiding loss in precision. #68


  • Pretty print improvements for exceptions #67


  • Pretty module #66


  • Proper handling of String "+123" #64


  • Function to print prettier parse exceptions #59


Add the Data.Yaml.Include module