Install

The current hledger release is 1.42.2. Here are the release notes.

Here are several ways you can install hledger:

  • Install official binaries from Github. (Always up to date.)
  • Install packaged binaries using your package manager. (Sometimes less up to date.)
  • Build your own binaries from the hledger source code. (Requires about 4G of RAM & disk and some time.)

As the final step, check your installation.

Official binaries

Official release binaries are provided for Linux, Mac, and Windows. Here's an RSS RSS feed.
Download them manually, or use eget (recommended). (For prerelease binaries, add --pre-release):

hledger release binaries eget simonmichael/hledger --all

Packaged binaries

Homebrew (Mac, Linux)
Homebrew brew install hledger

Docker (Linux, Mac, Windows) (more)
Docker docker pull dastapov/hledger

Windows
Scoop scoop install hledger
Winget winget install -e --id simonmichael.hledger
Chocolatey choco install hledger -y

BSD
freebsd ports pkg install hs-hledger hs-hledger-ui hs-hledger-web
openbsd ports pkg_add hledger

Nix (Linux, Mac) (Troubleshooting, #1030, #1033, #2089)
Nix nix-shell -p hledger hledger-ui hledger-web

GNU/Linux
Alpine
Alpine edge doas apk add hledger hledger-ui hledger-web
Alpine 3.21
Alpine 3.20
Alpine 3.19
Alpine 3.18
Arch
Arch pacman -Sy hledger hledger-ui hledger-web
Debian (more):
Debian unstable sudo apt install hledger hledger-ui hledger-web
Debian testing
Debian stable
Debian oldstable
Fedora (more)
Fedora_42 sudo dnf install hledger
Fedora_41
Fedora_40
Fedora_39
Fedora_38
Gentoo
Gentoo sudo eselect repository enable haskell && sudo emerge hledger hledger-ui hledger-web
Raspberry Pi
Raspberry Pi release binaries hledger-linux-arm32v7.zip
Raspberry Pi contributed binaries hledger-aarch64-manjaro.gz , hledger-armhf32-debian.gz (unaudited)
Ubuntu (more)
ubuntu_24_10 sudo apt install hledger hledger-ui hledger-web
ubuntu_24_04
ubuntu_22_04
ubuntu_20_04
ubuntu_18_04
Void
Void Linux x86_64 xbps-install -S hledger hledger-ui hledger-web

Sandstorm (web)
Sandstorm HLedger Web sandstorm app

Build from source

Building hledger requires the GHC compiler and either the stack or cabal build tool which you can install with your package manager (brew, apt, winget..), with ghcup, or with stack (simplest). Or, you can use docker. All this may need perhaps 4G of RAM and 4G of disk space.

On Mac

You will need the XCode Command Line Tools. Homebrew or macports will probably also be helpful.

Old issues:

On Unix/Linux

You will need a UTF-8-aware locale configured. You may also need to install extra C libraries, to avoid build errors like "cannot find -ltinfo". Eg:

  • On Debian or Ubuntu: sudo apt install libgmp-dev libtinfo-dev zlib1g-dev
  • On Fedora or RHEL: sudo dnf install gmp-devel ncurses-devel zlib-devel

Get the hledger source code with git:

git clone https://github.com/simonmichael/hledger
cd hledger
git checkout 1.42.2   # switch to the latest release tag (optional)

Then build and install with stack:

stack update; stack install

or with cabal:

cabal update; cabal install all:exes

or with docker:

cd docker; ./build.sh   # or build-dev.sh to keep build artifacts

Old issues:

On Windows

These notes are for Windows 11. On Windows, stack is the easiest way to get the haskell tools. (Though if you are on a Windows ARM machine, stack will install slow x86_64 versions of the tools, and build slow x86_64 hledger binaries.)

First, apply all windows updates (to get the latest TLS certificates for network requests).

Install stack - in a command or powershell window, run:

winget install -e --id commercialhaskell.stack

Install git:

winget install -e --id Git.Git

Get the hledger source:

git clone https://github.com/simonmichael/hledger
cd hledger
git checkout 1.42.2   # switch to the latest release tag (optional)

Build and install hledger:

stack update
stack install

On Windows, this may die repeatedly with a "... permission denied (Access is denied.)" error; we don't know why. Just run it again to continue (press up arrow, enter).

On Windows, things work best if you build in the environment where you will use hledger. Eg don't build it in a WSL or MINGW window if you plan to use it in CMD or Powershell.

Old issues:

On Nix

Old issues:

On Android

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

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 the hledger CLI to use less time and space: instead of stack install, run stack install hledger
  • It's ok to kill a build and rerun the command later; you won't lose progress.
  • You can add --dry-run to the install command to see how much building remains.

Check your installation

If your hledger is new enough (a pre-release), you should now run:

hledger setup

to check your setup. If this doesn't work, read on..

PATH

After installing, try to run the hledger tools (hledger, hledger-ui, hledger-web) and look for the expected versions. Eg:

$ hledger --version
hledger 1.42.2, mac-aarch64

If this doesn't work, you may need to add the binaries' install directory to your shell's PATH.

stack or cabal show the install directory in their output, and warn you if it is not in PATH. It could be, eg:

  • ~/.local/bin or C:\Users\USER\AppData\Roaming\local\bin\ (stack)
  • ~/.cabal/bin or C:\Users\USER\AppData\Roaming\cabal\bin\ (cabal)

On unix, these commands will add both bin directories to PATH permanently (probably):

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

On Windows, here's how to set environment variables.

Locale

hledger expects data files to use the same text encoding that is configured in the system locale. Otherwise you will see program-terminating errors when processing non-ascii characters. (#73)

The most common encoding to use is UTF-8. Some Linux and Nix systems use the C locale, which can handle ASCII text only. You should reconfigure these to C.UTF-8, usually by setting the LANG environment variable. Eg:

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

On some systems the exact punctuation and capitalisation is important; and the locale you have named may need to be installed. Check which locales are installed with locale -a, and see also Troubleshooting.

On Nix or GUIX, the procedures are different.

On Windows, you should probably check the "Use Unicode UTF-8 for worldwide language support" checkbox in Region Settings. Here's where it is in Windows 11: windows 11 UTF-8 setting

Completions

If you use the bash or zsh shells, you can set up context-sensitive auto-completions for hledger command lines. (Here's how to contribute other shells.)

bash

  1. Ensure that bash-completion is installed and enabled:

    On a Mac, using homebrew:

    • brew remove -f bash-completion
    • brew install bash-completion@2
    • Add the suggested line to your ~/.bash_profile, if it's not already there
    • source ~/.bash_profile (or open a new bash shell)

    On GNU/Linux:

    • apt install bash-completion
    • source ~/.bash_profile (or open a new bash shell)

  2. Install hledger with your system package manager (brew install hledger, apt install hledger or similar).

    Now completions may be working.

    If not, eg because your system's hledger package does not yet include the bash completions, or if they are not up to date, or if you have installed hledger by other means, then install the latest hledger bash completions yourself, under your XDG_DATA_HOME directory. Eg:

    curl https://raw.githubusercontent.com/simonmichael/hledger/1.42-branch/hledger/shell-completion/hledger-completion.bash \
  -o ~/.local/share/bash-completion/completions/hledger --create-dirs

Here's what the bash completions should complete when you press TAB once or twice in a command line:

Before the command argument:

  • the "hledger", "hledger-ui" and "hledger-web" executable names
  • general flags and flag values
  • hledger's command argument. Eg hledger <TAB><TAB> should list all hledger commands, and hledger b<TAB><TAB> should list the ones starting with b.

After the command argument:

  • command-specific flags and flag values
  • account names
  • query prefixes, like payee: or status:
  • valid query values after these query prefixes: acct:, code:, cur:, desc:, note:, payee:, real:, status:, tag:. Eg hledger reg acct:<TAB><TAB> should list your top-level account names.
  • amount comparison operators after amt:.

When a completion includes special characters, backslashes will be inserted automatically; this does not work right in all cases.

zsh

  1. Ensure that zsh-completions is installed and enabled.
  2. ? discussion

Next steps

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