Install
The current hledger release is 1.42.1. 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 feed.
Download them manually,
or use eget (recommended).
(For prerelease binaries, add --pre-release
):
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):
sudo apt install hledger hledger-ui hledger-web
Fedora (more)
sudo dnf install hledger
Gentoo
sudo eselect repository enable haskell && sudo emerge hledger hledger-ui hledger-web
Raspberry Pi
hledger-linux-arm32v7.zip
hledger-aarch64-manjaro.gz ,
hledger-armhf32-debian.gz (unaudited)
Ubuntu (more)
sudo 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 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.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.42.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:
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
, runstack 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.1-gdaafa059a-20250312, 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
orC:\Users\USER\AppData\Roaming\local\bin\
(stack)~/.cabal/bin
orC:\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:
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
-
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, andhledger 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:
orstatus:
- valid query values after these query prefixes:
acct:
,code:
,cur:
,desc:
,note:
,payee:
,real:
,status:
,tag:
. Eghledger 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.