Install

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

You can install hledger by any of these methods:

• Install official binaries from Github (quick)
• Install packaged binaries (quick; not always up to date)
• Install binaries you build from source (takes longer)

and then, check your setup.

Official binaries

Official release binaries for Linux, Mac, and Windows are provided in the hledger github repo. You can click the badge below to install them manually, or copy-paste the install command from Get hledger installed, or use a download tool like eget:

eget simonmichael/hledger --all

Packaged binaries

Homebrew (Mac, Linux)
brew install hledger

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

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

BSD
pkg install hs-hledger hs-hledger-ui hs-hledger-web
pkg_add hledger

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

GNU/Linux

Alpine
doas apk add hledger hledger-ui hledger-web

Arch
pacman -Sy hledger hledger-ui hledger-web

Debian (more):
apt install hledger hledger-ui hledger-web

Fedora (more)
dnf install hledger

Gentoo
eselect repository enable haskell && emerge hledger hledger-ui hledger-web

Raspberry Pi (unaudited)
hledger-linux-arm32v7.zip
hledger-aarch64-manjaro.gz , hledger-armhf32-debian.gz

Ubuntu (more)
apt install hledger hledger-ui hledger-web

Void
xbps-install -S hledger hledger-ui hledger-web

Sandstorm (web)
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 or more of disk space.

On Mac

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

Old issues:

• mac m1: building with ghc 9+ requires extra include dir

On Unix/Linux

You will need

1. The header files for certain C libraries, which stack/cabal can't install for you; otherwise you'll see build errors like "cannot find -ltinfo". The exact package names will be specific to your system, but here are some likely install commands:

   • Debian-based systems: apt install libgmp-dev libncurses-dev zlib1g-dev
   • Older Debian systems: apt install libgmp3-dev libncurses5-dev zlib1g-dev
   • Redhat-based systems: dnf install gmp-devel ncurses-devel zlib-devel
   • Arch: pacman -S gmp ncurses zlib
   • Alpine: apk add gmp-dev ncurses-dev zlib-dev
   • openSUSE: zypper install gmp-devel ncurses-devel zlib-devel
   • FreeBSD: pkg install gmp ncurses

2. A configured system locale that specifies a text encoding; otherwise you'll see text decoding errors when processing non-ascii characters. For example, on most unix systems echo $LANG should show something like en_US.UTF-8 or zh_CN.GB2312 or C.UTF-8 - it should not be just C, or unset. This is discussed more in Text encoding, below.

Get the hledger source code with git:

git clone https://github.com/simonmichael/hledger
cd hledger
git checkout 1.51.1   # 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:

• arch: haskell build advice from Arch wiki
• openbsd 6: exec: permission denied
• openbsd: stack install tips

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.51.1   # 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:

• windows: cross-environment non-ascii display issues

On Nix

Old issues:

• nix: nix install on linux can fail with "cloning builder process: Operation not permitted"
• nix: on Linux, nix-installed hledger won't handle non-ascii data

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 setup

With modern hledger versions, you should now run:

hledger setup

to check your installation. 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.51.1-...-20251208, 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

Data files containing non-ascii characters are saved with a text encoding - UTF-8, Latin-1, CP-437, or something else. hledger uses the system's text encoding when reading data, and it expects data to use the same encoding. So if no system encoding is configured, or if the data uses a different encoding, hledger will give an error when reading it.

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 may see this problem if you are working with files received from another system, eg from a Windows system.

• On Windows, the system encoding varies by region. You probably won't see this problem if you are working with your own data (perhaps depending how you create the data - see Start a journal). 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 use (see below).

• On GNU/Linux and other unix systems, the system encoding varies, and sometimes is not configured at all. It may be controlled by the LANG environment variable, or in other ways. You should ensure that at least some encoding is configured. UTF-8 is usually a good choice.

If you hit this problem, you can solve it by

• converting the data files to your system's text encoding. Use iconv on unix/mac, powershell or notepad on Windows.
• configuring your system encoding to match your data files.
• or (for CSV/SSV/TSV files only), use the encoding CSV rule.

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: 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.50-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 Docs, or come to the #hledger chat where we'll gladly share tips or receive your feedback.