dhall-haskell: the Haskell implementation of the Dhall configuration language

This repository is the bindings, not the language

The readme opens by pointing you somewhere else, and that is the most useful thing in it. You will probably want to read the language-agnostic README, which lives in the dhall-lang repository, because this repository focuses on the Haskell bindings to Dhall. That distinction matters when you are evaluating the project. Dhall the language is defined once, and other implementations exist, so a decision to use Dhall is a decision about the language, and this repository is the part that makes it real for a Haskell shop. The project description is the maintainable configuration files, which is the claim on the table, and the Haskell side is what has to deliver it in practice. The layout reflects that division. Each package is its own directory with its own README, each is published on Hackage, and the top level is a build workspace with Cabal, Nix and Stack configurations side by side.

The package set, and what each one is for

Nine packages are listed in the readme, and they divide neatly into the core, the format converters and the tooling. The dhall package is the core library and command line tool. The converters are dhall-json, dhall-yaml, dhall-toml, dhall-csv, dhall-bash and dhall-nix, and the point of that set is interoperability, since a configuration written in one format and consumed by a tool that only understands another needs a converter in between. dhall-bash and dhall-nix are the interesting pair, because they target shell and Nix consumers rather than data formats, which tells you the project expects Dhall to sit in the middle of a build pipeline rather than only at its edges. The tooling is dhall-lsp-server, a language server for editors, and dhall-docs, a documentation generator. The tree also holds packages the readme does not list, including dhall-text, dhall-try, dhall-openapi, dhall-test-server and dhall-nixpkgs, and a directory of ide_features.txt that lists what an editor integration should offer.

Three ways to get a binary, and a trick for pull requests

You do not have to build from source to use this. Pre-built binaries for Windows, OS X and Linux are on the release page, and on macOS Homebrew is the short path:

$ brew install dhall-json

For Linux, the project uses Nix, and the readme describes two routes. You can install pre-built binaries for master using the channel mechanism, following the instructions for the Hydra jobset, or you can configure your machine to use cache.dhall-lang.org and then visit a per-package URL, one for the core tool and one for each converter, the language server, the docs generator and the rest. The Hydra pages have a Help button in the bottom right corner that shows the nix-env command to run. If you have the jq command line tool installed, the whole thing collapses into one command:

$ nix-env -i "$(curl -L https://hydra.dhall-lang.org/job/dhall-haskell/master/linux-dhall/latest/api/get-info | jq -r .outPath)"

And the readme notes something that is genuinely useful for contributors, the same instructions work for any pull request if you replace master with the pull request number in the URLs. That means a reviewer can install the exact build a contributor is proposing without building it themselves.

Containers for releases, image archives for master

Container images are published for the latest release on Docker Hub under the dhallhaskell account, one image per package. For bleeding-edge builds, the readme gives a different route, downloading image archives for each package as tarballs from Hydra, with a URL per package, including the core, bash, json, yaml, the language server, nix, docs, toml and csv. You then load and run one of those archives locally, which is the pattern for getting a build of a commit that has not been released without waiting for a tag. Two details are worth noting for anyone automating this. The images are per package rather than one image with everything, which keeps each one small, and the archive route depends on the same Hydra jobset as the Nix builds, so a broken CI run takes the container route down with it.

A build matrix covering seven GHC versions

The build configuration shows how seriously the project takes compatibility. There is a cabal.project for Cabal users, a default.nix and a release.nix and a shell.nix for Nix users, and a stack.yaml plus a stack file for every supported compiler, named stack.ghc-8.10.yaml, stack.ghc-9.2.yaml, stack.ghc-9.4.yaml, stack.ghc-9.6.yaml, stack.ghc-9.8.yaml, stack.ghc-9.10.yaml and stack.ghc-9.12.yaml. Seven GHC versions, from 8.10 through 9.12, tested side by side, is a compatibility surface most libraries do not attempt, and it is the right call for a package other tools depend on. The linting and formatting configuration is in the tree as well, with an .hlint.yaml for HLint and a .stylish-haskell.yaml for stylish-haskell, which is the usual Haskell pairing for keeping a codebase consistent. There is also a .mergify.yml, the configuration for the merge automation service, which tells you pull requests are merged by a bot when they satisfy the rules.

Benchmarks live in the repository

Three benchmark scripts sit at the top level, run_parser_benchmarks.sh, run_evaluation_benchmarks.sh and run_cli_evaluation_benchmarks.sh, with a plot_benchmark_results.py to turn the results into a chart. That last file is the reason the repository's primary language is listed as Python, which is a small curiosity worth noticing: the project is Haskell and the benchmark plotting script is not. The split between the three scripts is informative on its own, since a parser benchmark, an evaluation benchmark and a command line evaluation benchmark are three different things to measure, and a configuration language is only as good as its evaluation performance for a large file. The scripts and the plotting tool are part of the repository rather than a side project, so the numbers can be reproduced by anyone who wants to check them.

Where the project stands

The release history is the last thing to look at, because it tells you what to expect. The tags are 1.42.0 from April 2023, 1.42.1 from December 2023 and 1.42.2 from January 2025, so the project is on a 1.42 line with releases roughly a year apart, and the last push was on 2026-10-19, which means the repository is being worked on more recently than the last tag. That combination, a slow release cadence on a version line that is still 1.x, tells you this is a mature but slowly moving project rather than a fast moving one, which is what you would expect of a configuration format that other people's build systems depend on. The licence is BSD-3-Clause, the project site is dhall-lang.org, and the documentation for the language itself lives in the separate dhall-lang repository, with this repository holding the packages that implement it.

Editorial conclusion

dhall-haskell is the right choice if you are in the Haskell world and you want a configuration format you can generate, transform and check rather than a pile of templates, and the converters are what make it usable next to tools that only read JSON or YAML. It is the wrong choice if you do not want a Haskell toolchain in your path at all, since the ecosystem around the language is young and the release cadence is slow, with the newest tag from January 2025. Before you commit, read the language-agnostic README in the dhall-lang repository, since this repository is only the bindings, and check the Docker Hub images or the Nix channel rather than assuming a package manager has it.

Frequently asked questions

Official sources

1. dhall-lang/dhall-haskell on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases