Install
The current hledger release is 1.41. 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
Homebrew (Linux, Mac, WSL)
Docker (Linux, Mac, Windows)
docker pull dastapov/hledger
more..
Windows
scoop install hledger
choco install hledger -y
winget install simonmichael.hledger
Linux
doas apk add hledger hledger-ui hledger-web
enabling the community repository
pacman -Sy hledger hledger-ui hledger-web
sudo apt install hledger hledger-ui hledger-web
more..
sudo dnf install hledger
more..
sudo layman -a 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
pkg_add hledger
Nix (Linux, Mac)
nix-shell -p hledger hledger-ui hledger-web
Issues:
#1030,
#1033,
#2089,
Troubleshooting
Sandstorm (Web)
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.
On unix systems, 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:
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. It installs build tools if needed, then builds the current release of the hledger tools and some add-on tools, installing 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 # <- optional, good practice: inspect downloads 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 (good if you plan to do a lot of Haskelling).
Once stack is installed, run these commands:
stack update
stack install base-compat-0.14.0 hledger-lib-1.41 hledger-1.41 hledger-ui-1.41 hledger-web-1.41 \
--resolver=lts-23 --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 another 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:
cabal update
cabal install hledger-1.41 hledger-ui-1.41 hledger-web-1.41
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,
get it with git (to get a release branch instead, add eg -b 1.41
):
git clone https://github.com/simonmichael/hledger
cd hledger
When in this directory you can build and install with:
stack update
stack install
or:
cabal update
cabal install all:exes
Build in a Docker container
This will use a docker image with the necessary build tools pre-installed:
cd hledger/docker
./build.sh # or build-dev.sh to keep build artifacts
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):
- mac m1: building with ghc 9+ requires extra include dir
- windows: cross-environment non-ascii display issues
- arch: haskell build advice from Arch wiki
- openbsd 6: exec: permission denied
- openbsd: stack install tips
- 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
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 1.41, ...
$ hledger-ui --version
hledger-ui 1.41, ...
$ hledger web --version
hledger-web 1.41, ...
You can run the built-in unit tests if you'd like:
$ hledger test
...
All 227 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 1110 ...
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 most unix systems, when you are processing non-ASCII text with hledger,
the LANG
environment variable must be set to a suitable locale to ensure hledger can decode the text,
avoiding errors like "invalid byte sequence" or "mkTextEncoding: invalid argument".
This applies to the Haskell build tools like GHC, cabal and stack, as well.
We usually recommend the UTF-8 text encoding.
On unix-like systems, check that your LANG
setting 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 Microsoft Windows, I read that this might help in powershell:
$env:LC_ALL = "C.UTF-8"
$env:LANG = "C.UTF-8"
or this in CMD:
set LC_ALL=C.UTF-8
set LANG=C.UTF-8
There are also lots of ways to get pre-built binaries for Windows, if you don't need to build your own: https://hledger.org/install.html
On Nix or GUIX, the procedures are different.
Shell completions
If you use the bash shell, you can optionally set up context-sensitive autocompletions when you press TAB in a hledger command line (see demo). To contribute completions for another shell, see hledger/shell-completion/README.
First, test if completions are already working: at a bash shell prompt,
hledger<SPACE><TAB><TAB>
should list all hledger commandshledger reg acct:<TAB><TAB>
should list your top-level account names.
If not, first 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)
...
Then, after using your system package manager to install hledger (brew install hledger
, apt install hledger
or similar),
completions may be working.
If your system's hledger package does not yet include completions, or if they are not up to date, or if you have installed hledger by other means, then install the latest hledger completions yourself, under your XDG_DATA_HOME directory. Eg:
curl https://raw.githubusercontent.com/simonmichael/hledger/1.41-branch/hledger/shell-completion/hledger-completion.bash \
-o ~/.local/share/bash-completion/completions/hledger --create-dirs
Here are all the things you can complete by pressing TAB once or twice:
- the "hledger", "hledger-ui" and "hledger-web" commands
- hledger's command argument
- general flags
- command-specific flags, after the command argument
- flag values, for flags that have standard values
- query prefixes
- account names from the journal, after an account name prefix
- appropriate data from the journal, after these query prefixes:
acct:
,code:
,cur:
,desc:
,note:
,payee:
,real:
,status:
,tag:
- amount comparison operators, after
amt:
.
When a completion includes special characters, backslashes will be inserted automatically; this does not work right in all cases.
Next steps
Nicely done! Now see Get started, or come to the #hledger chat where we'll gladly share tips or receive your feedback.