Install

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

There are three main ways to install hledger on your computer:

Release binaries are provided by hledger's maintainer and are always up to date.
Packaged binaries are provided by system packagers and are sometimes less up to date.
Or you can build your own binaries, which takes more time and resources.

After installing, there are some final things to check. Your feedback helps make this process smoother.

Release binaries

Official release binaries for Linux, Mac, Windows.

Packaged binaries

scoop install hledger
winget install hledger
Installs to C:\Users\Simon\AppData\Local\Microsoft\WinGet\Links\hledger.exe. On ARM machines this runs via emulation (slower than normal). hledger-ui and hledger-web aren't available via winget yet.

choco install hledger -y

Linux

doas apk add hledger hledger-ui hledger-web

pacman -Sy hledger hledger-ui hledger-web

sudo apt install hledger hledger-ui hledger-web

more..

sudo dnf install hledger

more..

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

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

sudo apt install hledger hledger-ui hledger-web

more..

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

BSD

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

Nix (Linux, Mac)

nix-shell -p hledger hledger-ui hledger-web
Issues: #1030, #1033, #2089, Troubleshooting

Sandstorm (Web)

HLedger Web sandstorm app

Build from source

Build requirements

Building hledger requires the GHC compiler and either the stack or cabal build tool. These are usually easy to install (see below). But they will require quite a bit of memory and disk space - up to 4G of RAM and 2G of your hard drive to build the hledger tools. See also the build tips below.

Build on Unix/Linux/Mac

On unix systems (most machines, except Windows), you will need a UTF-8-aware locale configured. Also you may need to install additional C libraries to avoid errors like "cannot find -ltinfo" when building hledger. 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

Here are some ways to build hledger on unix:

Build with hledger-install

hledger-install.sh is an automated install script that requires only bash. This is a good choice if you are not used to building Haskell software (and if you are using a unix-based system, not Windows). hledger-install.sh downloads Haskell build tools if needed, then builds the current release of the hledger tools, plus a number of add-on tools, and installs them in ~/.local/bin. (Or ~/.cabal/bin, if you had cabal and not stack installed.)

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

Build with stack

stack is a reliable Haskell build tool. You can install it

with your system package manager
or from its website
or with ghcup (this is ideal if you plan to do more Haskelling).

Once stack is installed, run:

stack update
stack install hledger-1.42.1 hledger-ui-1.42.1 hledger-web-1.42.1 \
  --resolver=nightly-2025-03-01 --verbosity=error

stack will install a compatible version of the GHC compiler if needed, perhaps using ~2G of disk space (under ~/.ghcup if it is configured to use ghcup, otherwise under ~/.stack). Then it will build the hledger tools and install them in ~/.local/bin.

Build with cabal

cabal is the other popular Haskell build tool. You can install it with your system package manager. You will also need to install a version of GHC that can build current hledger; usually any version newer than 8.10.7 will do. Or, you can install both of these with ghcup.

Then run:

cabal update
cabal install hledger-1.42.1 hledger-ui-1.42.1 hledger-web-1.42.1

This will build the hledger tools and install them in ~/.cabal/bin.

Build in a source checkout

If you'd like to build the latest hledger source code, download that first with git:

git clone https://github.com/simonmichael/hledger
cd hledger
git checkout 1.42.1   # optional: switch to release tag

Now you can build and install this source with:

stack update
stack install

or:

cabal update
cabal install all:exes

or:

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

Build on Windows

These notes are for WIndows 11. Some things may apply to older Windows versions as well.

stack
On Windows, stack is the easiest way to get a haskell toolchain. stack will install GHC and other tools for you automatically. You can install stack with winget install commercialhaskell.stack. On ARM machines, stack currently will install x86_64 versions of GHC, which will build x86_64 hledger binaries, and all of these will run via emulation (slowly).

ghcup
If you want more control over your haskell toolchain, to more easily see what's installed and manage tool versions and disk space, you could install ghcup. Then you can use ghcup tui to install ghc and either stack or cabal. (These docs focus on stack. If you are using both ghcup and stack, install stack via ghcup, so that stack will leave ghc management to ghcup.) ghcup isn't yet easy to install on ARM machines, however.

Windows updates
For stack and probably other haskell tools, you need to apply all windows updates to get the latest TLS certificates, so that network requests will work.

Build and install
Then you could run stack install hledger. This would build the hledger version from the current stackage LTS snapshot, which is not always the latest release. So instead, it's better to use the latest stack install command shown above. Here it is as a one-line command you can paste into a Windows CMD or powershell window:

stack update & stack install hledger-1.42.1 hledger-ui-1.42.1 hledger-web-1.42.1 --resolver=nightly-2025-03-01 --verbosity=error

On Windows, the build may die repeatedly with a "... permission denied (Access is denied.)" error; we don't know why. Each time, you have to run it again to continue (up arrow, enter).

When complete, it installs executables at eg C:\Users\Simon\AppData\Roaming\local\bin\hledger.exe.

Build 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, by omitting hledger-ui and hledger-web.
It's ok to kill a build and rerun the command later; you won't lose progress.
You can add --dry-run to 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.

Here are some known build issues and workarounds on various platforms (possibly obsolete):

Check your installation

After installing, 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-ui --version; hledger-web --version
hledger 1.42.1-gdaafa059a-20250312, mac-aarch64
hledger-ui 1.42.1-gdaafa059a-20250312, mac-aarch64
hledger-web 1.42.1-gdaafa059a-20250312, mac-aarch64

You can run the built-in unit tests if you'd like:

$ hledger test
...
All 234 tests passed (0.04s)

or the more thorough functional tests, if you are set up for working with the hledger source code:

$ just functest
...
 Total   1133 ...
functest PASSED

PATH

If the hledger tools won't run at the command line or you don't see the expected --version output, check that the newly installed executables are first in your shell's PATH. After building/installing, you may have seen a message about where the executables were installed. Eg:

If you installed with stack, it's $HOME/.local/bin (on Windows, %APPDATA%\local\bin)
If you installed with cabal, it's $HOME/.cabal/bin (on Windows, %APPDATA%\cabal\bin)
If you installed with nix, it could be $HOME/.nix-profile/bin

Make sure that this bin directory is included in your shell's PATH setting, and preferably near the start of the list, 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" >> ~/.profile
source ~/.profile

Here's how to set environment variables on Windows.

Text encoding

On Microsoft Windows:

For hledger-web, you might need to check the "Use Unicode UTF-8" checkbox in Region Settings (like this).

For hledger or hledger-ui in a powershell window, possibly this might help:

$env:LC_ALL = "C.UTF-8"
$env:LANG = "C.UTF-8"

or in a CMD window:

set LC_ALL=C.UTF-8
set LANG=C.UTF-8

On most unix systems:

When your hledger data contains non-ASCII characters (as is usually the case), the LANG environment variable must be set to a suitable locale to ensure hledger can decode the text, preventing error messages like "invalid byte sequence" or "mkTextEncoding: invalid argument". (This applies to the Haskell build tools like GHC, cabal and stack, as well.)

We most often recommend the UTF-8 text encoding. Check that your LANG variable mentions UTF-8, and if not, change it. Eg:

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

On Nix or GUIX:

The procedures are different.

Shell completions

If you use the bash or zsh shells, you can optionally set up context-sensitive autocompletion for hledger command lines. Here's an old demo. To contribute completions for other shells, see hledger/shell-completion/README.

bash

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)
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

Ensure that zsh-completions is installed and enabled.
? 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.

hledger