Install

The current hledger release is 1.28. (Release notes)

Here are lots of ways to install hledger:

After downloading binaries or building from source, please check that the run requirements (PATH and locale) are satisfied.

And finally please share any feedback so we can make this process smoother!


Binary packages

Mac

hledger CI binaries
Homebrew
brew install hledger

Windows

hledger CI binaries
scoop install hledger
choco install hledger -y

GNU/Linux

hledger CI binaries
Gentoo
sudo layman -a haskell && sudo emerge hledger hledger-ui hledger-web
Arch
pacman -Sy hledger hledger-ui hledger-web
Alpine edge
doas apk add hledger hledger-ui hledger-web
Void Linux x86_64
xbps-install -S hledger hledger-ui hledger-web
sudo dnf install hledger
sudo apt install hledger hledger-ui hledger-web
sudo apt install hledger hledger-ui hledger-web

Raspberry Pi

hledger CI binaries
Contributed binaries
Note: unaudited third party binaries

BSD

openbsd ports
pkg_add hledger
netbsd package
pkg_add hledger
freebsd ports
pkg install hs-hledger hs-hledger-ui hs-hledger-web

Other

docker pull dastapov/hledger
Nix
nix-env -f https://github.com/NixOS/nixpkgs/archive/86378514.tar.gz -iA hledger_1_26 hledger-ui_1_26 hledger-web_1_26
Install command untested, success/failure reports welcome.
Nix binaries may not yet be fully cached for your platform, try with --dry-run to estimate how much building will be required.
On Linux, note #1030, #1033.
Sandstorm

Preview releases

hledger CI binaries
Previews of the next major release, for testers & early adopters.

Build the current release

Release source
  1. Check build requirements
  2. Use one of the build methods

Build requirements

Hardware

  • A machine where the Haskell build tools are available.
  • 4G of RAM is recommended.
  • 2G of free disk space will be needed if this is your first Haskell build.

GHC, stack, cabal

These are the Haskell build tools. If you choose the "Build with hledger-install" method below, they will be installed automatically. If you choose the "Build with stack" method, you will need to have stack installed. If you choose the "Build with cabal" method, you will need to have cabal and GHC installed.

You can probably install these tools with your local packaging system. They need not be the latest versions (but later versions are better):

  • GHC should be >=8.8. On Arch GNU/Linux, the packaged GHC is non-standard and may be troublesome.
  • cabal (ie cabal-install) should be >=3.2.
  • stack should be >=2.7. You can often upgrade an existing stack installation quickly with stack upgrade. On Windows, prefer the 64-bit version of stack.

Or, you can install them with ghcup.

If you don't have any preference, I recommend this setup, which is the most reliable and platform-independent as of 2022:

  1. Install ghcup
  2. Install a recent version of ghc and stack
    ghcup install ghc
    ghcup install stack
  3. Configure stack to use ghcup's GHCs, saving disk space:
    # add to ~/.stack/config.yaml:
    system-ghc: true
    install-ghc: false
    

C libraries

On unix systems, you may need to install additional C libraries to avoid errors like "cannot find -ltinfo" when building hledger. Install them with a command like the below:

Debian, Ubuntu & co.:
sudo apt install libgmp-dev libtinfo-dev zlib1g-dev
Fedora, RHEL:
sudo dnf install gmp-devel ncurses-devel zlib-devel

(Please send updates for this list.)

UTF-8 locale

On unix systems, when building hledger the LANG environment variable must be set to a UTF-8-aware locale. See Check your locale.

Known build issues

More build tips

  • Building the hledger tools and possibly all their dependencies could take anywhere from a minute to an hour.

  • On machines with less than 4G of RAM, the build may use swap space and take much longer (overnight), or die part-way through. In such low memory situations, try adding -j1 to the stack/cabal install command, and retry a few times, or ask for more tips.

  • You could build just hledger CLI to use less time and space, by omitting hledger-ui and hledger-web from the commands below.

  • It's ok to kill a build and rerun the command later; you won't lose progress.

  • You can add --dry-run to the stack/cabal/nix install commands to see how much building remains.

  • If you have previously installed the hledger tools, they will usually be overwritten by the new version. If you have them installed in multiple places in your PATH, you may see a warning, reminding you to remove or rename the old executables.

Build methods

Use any of the following methods:

Build with hledger-install

The hledger-install.sh script builds the current release of the hledger tools, plus some add-ons, in a relatively reliable way, requiring bash but not any Haskell build tools. It uses stack or cabal if you have them (installing stack in ~/.local/bin otherwise), and installs the hledger tools in ~/.local/bin or ~/.cabal/bin respectively. This can be a good choice if you are new to Haskell.

curl -sO https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh
less hledger-install.sh # <- good security practice: inspect downloaded scripts before running
bash hledger-install.sh

Build with stack

If you have stack installed, you can run it to install the main hledger tools in ~/.local/bin:

stack update
stack install --resolver=lts-19 hledger-lib-1.28 hledger-1.28 hledger-ui-1.28 hledger-web-1.28 --silent

On Windows, omit hledger-ui from this command (unless you are in WSL).

Build with cabal

If you have GHC and cabal, you can run cabal to install the main hledger tools in ~/.cabal/bin:

cabal update
cabal install alex happy
cabal install hledger-1.28 hledger-ui-1.28 hledger-web-1.28

On Windows, omit hledger-ui from this command (unless you are in WSL).

Build with nix

If you have nix, you can use nix-env to build hledger from source (but we try to provide a nix command that installs already-cached binaries, see above).

Build on Android

Here's how to build hledger on Android with Termux (if your phone has plenty of memory).

Build the development version

Latest source

If you want the very latest improvements, our master branch on github is suitable for daily use.

  1. Check build requirements above

  2. Get the source with git and enter the source directory:

    git clone https://github.com/simonmichael/hledger
    cd hledger
  3. Build and install executables (to ~/.local/bin) with stack:

    stack update
    stack install

    or (to ~/.cabal/bin) with cabal:

    cabal update
    cabal install alex happy
    cabal install all:exes

    or you can build in a Docker container which includes the necessary tools and dependencies:

    git clone https://github.com/simonmichael/hledger
    cd hledger/docker
    ./build.sh

    (This will build the image tagged hledger with just the latest binaries inside. If you want to keep all the build artifacts and use the resulting image for hledger development, run ./build-dev.sh instead.)

Run requirements

After installing whether from binaries or from source,

by downloading binaries or by building from source, please check that the run requirements (PATH and locale) are satisfied.

by any of the methods above, run the hledger tools and verify that their versions are what you just installed (and not older versions from a previous install). Eg:

$ hledger --version
hledger 1.28-g6e130a4b6-20221201, mac-aarch64

$ hledger-ui --version
hledger-ui 1.28-g6e130a4b6-20221201, mac-aarch64

$ hledger web --version
hledger-web 1.28-g6e130a4b6-20221201, mac-aarch64

If you like, you can also run the unit tests:

$ hledger test
...
All 217 tests passed (0.10s)

or the more extensive functional tests, if you are in hledger's source directory:

$ make functest
...
Total 934 ...
functest PASSED

If things are not yet working, then:

Check your PATH

After building/installing, you may see a message about where the executables were installed. Eg:

  • with stack: $HOME/.local/bin (on Windows, %APPDATA%\local\bin)
  • with cabal: $HOME/.cabal/bin (on Windows, %APPDATA%\cabal\bin)
  • with nix: $HOME/.nix-profile/bin

Make sure that this install directory is included in your shell's $PATH (preferably near the start, to preempt any old hledger binaries you might have lying around). How to configure this depends on your platform and shell. Eg if you are using bash, this will show $PATH:

echo $PATH

and this will add the stack and cabal install dirs to it permanently:

echo "export PATH=~/.local/bin:~/.cabal/bin:$PATH" >> ~/.bashrc
source ~/.bashrc

Here's how to set environment variables on Windows.

Check your locale

On unix systems, when running hledger (and other GHC-compiled programs, like GHC, cabal & stack), the LANG environment variable must be set to a UTF-8-aware locale to avoid errors like "invalid byte sequence" or "mkTextEncoding: invalid argument" when processing non-ascii text.

Check that LANG's value mentions UTF-8, and if not, change it:

$ echo $LANG
C
$ export LANG=C.UTF-8    # or en_US.UTF-8, fr_FR.utf8, etc.
$ echo $LANG
C.UTF-8

In some cases the locale may need to be installed with your system package manager first. See hledger: Troubleshooting for more help.

If you see similar problems on Microsoft Windows, perhaps this doc can help with configuring it.

Next steps

Nicely done! Now see Getting started, or come to the #hledger chat where we'll gladly share tips or receive your feedback.