Install

The current hledger release is 1.43. 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 system locale with a text encoding configured; it might need to be UTF-8. 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.43   # 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.43   # 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.43, 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.

Text encoding

hledger expects non-ascii input to be decodable with the system locale's text encoding; usually if you try to read a file with a text encoding different from the system encoding, it will fail. This also applies to the Haskell build tools, if you are building hledger from source.

How likely is this to affect you ? It depends on your platform and the data you are working with:

  • On Mac, the system encoding is always UTF-8. You'll notice this problem only if you try to process files in a foreign encoding, eg received from a Windows user.

  • On Windows, the system encoding varies by region. If you are working with your own data, you won't notice this problem. If you are on Windows 11 and often need to share files with mac/unix systems, there is a setting for UTF-8 encoding which you might want to enable.

  • On GNU/Linux and other unix systems, the system encoding varies, and is sometimes none. You should ensure that at least some encoding is configured, so that you can work with non-ascii data. It may be controlled by the LANG environment variable, or in other ways.

If you hit this problem, you can

  • configure your system encoding to match the files you usually work with, if feasible. If you're not sure which encoding to use, pick UTF-8.
  • or, convert the files to your system's text encoding. Use iconv on unix/mac, powershell or notepad on Windows.
  • or, use the CSV encoding rule to auto-convert CSV(/SSV/TSV) files.

Here's an example. Let's say you want to work with UTF-8 text on a GNU/Linux system, but it's configured with the C locale, which can only handle ASCII text:

$ echo $LANG
C

So, first check that you have a UTF-8-capable locale installed (locale -a). If not, install one (perhaps by using your package manager, perhaps by uncommenting it in /etc/locale.gen and running locale-gen).

Then change the system locale. Here's one common way to set it permanently for your shell. Note exact punctuation and capitalisation of locale names is important on some systems.

$ echo "export LANG=C.utf8" >>~/.profile    # or en_US.UTF-8, fr_FR.utf8, etc.
# close the shell/terminal window and open a new one
$ echo $LANG
C.UTF-8

For Nix users, the procedure is different, eg you might need to set LOCALE_ARCHIVE instead. Likewise for GUIX users.

Windows users who want to use UTF-8 encoding, eg to interoperate with unix systems, might find the "Use Unicode UTF-8 for worldwide language support" setting helpful. Here's where it is in Windows 11: windows 11 UTF-8 setting Though it might cause problems with some older applications, including some GUI programs.

Here's a way to select UTF-8 for Windows Terminal and PowerShell, without affecting the entire system: add this line to the PowerShell profile file:

$OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding

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