Download/Install
The current hledger release is 1.21 (release notes). Below are lots of ways to install:
- Binary packages install quickly
- Building from source takes longer but ensures you get the latest release.
You may also need some C libraries or a UTF-8 locale.
Afterward, check your PATH and test your installation.
And, please report any roadbumps so we can fix them.
Binary packages
Multiplatform
Linux, Mac, Windows
|
docker pull dastapov/hledger
|
Linux, Mac, WSL
|
brew install hledger
|
Linux, Mac
|
nix-env -f https://github.com/NixOS/nixpkgs/archive/915ef210.tar.gz -iA hledger hledger-ui hledger-web
|
Linux, Mac, *BSD, ...
|
Install Wine and use the Windows binary below
|
Windows
|
|
Mac
|
GNU/Linux
|
|
Gentoo
|
sudo layman -a haskell && sudo emerge hledger hledger-ui hledger-web
|
Arch
|
pacman -S hledger hledger-ui hledger-web
|
Void
|
xbps-install -S hledger hledger-ui hledger-web
|
Debian
|
sudo apt install hledger hledger-ui hledger-web
|
Fedora
|
sudo dnf install hledger
|
Ubuntu
|
sudo apt install hledger hledger-ui hledger-web
|
FreeBSD
pkg install hs-hledger hs-hledger-ui hs-hledger-web
|
OpenBSD
make -C /usr/ports/openbsd-wip/productivity/hledger install
|
Raspberry Pi
|
|
|
Cloud
|
C libraries
On some platforms, certain C library packages must be installed, or you'll see an error (eg: "cannot find -ltinfo") when you try to run prebuilt hledger binaries or build hledger from source. So if you're on one of the following platforms, please run the command shown (and please send improvements for this list):
Debian, Ubuntu: |
sudo apt install libtinfo-dev libtinfo5 |
Fedora, RHEL: |
sudo dnf install gmp-devel ncurses-devel |
UTF-8 locale
On unix systems, when building or running hledger (and GHC haskell
programs in general), the LANG
environment variable must be set to a
UTF-8-aware locale, or you'll see errors (eg: "invalid byte
sequence" or "mkTextEncoding: invalid argument") when processing
non-ascii text. Check that LANG's value mentions UTF-8, and if not,
change it:
$ 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.
Building from source
The hledger-install script requires only bash and builds the current release of the hledger tools and some add-ons, in a reliable way:
less hledger-install.sh # <- good practice: inspect downloaded scripts before running
bash hledger-install.sh
This uses the stack or cabal build tools (installing stack in ~/.local/bin if needed), and installs the hledger tools in ~/.local/bin or ~/.cabal/bin.
Or, if you prefer to run stack yourself:
stack install --resolver=lts-17 hledger-lib-1.21 hledger-1.21 hledger-ui-1.21 hledger-web-1.21 --silent
This installs the main hledger tools in ~/.local/bin.
Your stack --version
should be not too ancient; use a recent release (2.5.1+) for best results.
You can usually upgrade stack quickly with stack upgrade
.
Windows users: the 64-bit version of stack is preferable;
and you should omit hledger-ui from this command, unless you are in WSL.
Or, if you prefer to run cabal yourself:
cabal install alex happy
cabal install hledger-1.21 hledger-ui-1.21 hledger-web-1.21
This installs the main hledger tools in ~/.cabal/bin.
Your cabal --version
should be not too ancient; use a recent release (eg 3.2+) for best results.
Windows users: omit hledger-ui from this command, unless you are in WSL.
Or, nix users can use nix-env to build hledger from source (but we try to provide a nix command that installs already-cached binaries.)
Build tips
-
You can build hledger from source wherever GHC is supported. It's normally routine, requiring no babysitting.
-
A build can require up to 2G of free RAM and disk space, and could take between a minute and an hour.
-
You can use less resources by omitting the hledger-ui and hledger-web packages from the commands above.
-
It's ok to kill a build and rerun the command later; you won't lose progress.
-
You can add
--dry-run
to the stack/cabal/nix install commands to see how much building remains. -
If you already have hledger tools installed, 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.
-
If you try to build with insufficient free RAM, it may use swap space and take a very long time (overnight). Or it may fail with an error; in this case try adding
-j1
to the stack/cabal install command and retry a few times, or ask for help. -
Here are some known build issues and workarounds on certain platforms:
windows: hledger-ui is not available
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
Building the development version
If you want the very latest improvements, our master branch on github is suitable for daily use. Get the source with git:
cd hledger
and build and install executables to ~/.local/bin with stack:
stack install
or to ~/.cabal/bin with cabal:
cabal install alex happy
cabal install all:exes
hledger development builds show a ".99" suffix in their --version
output,
so eg "1.17.99" means the in-development version of 1.18.
Building the development version with Docker
You can also build the development version in a Docker container which will take care of pulling all the necessary tools and dependencies:
cd hledger/docker
./build.sh
This will build the image tagged hledger
with just the latest binaries inside.
If you want to keep all the build artifacts and use the resulting
image for hledger development, run ./build-dev.sh
instead.
Check your PATH
After building/installing, you may see a message about where the executables were installed. Eg:
- with stack:
$HOME/.local/bin
(on Windows,%APPDATA%\local\bin
) - with cabal:
$HOME/.cabal/bin
(on Windows,%APPDATA%\cabal\bin
) - with nix:
$HOME/.nix-profile/bin
Make sure that this install directory is included in your shell's $PATH
(preferably near the start, to preempt any old hledger binaries you might have lying around),
so that you can run the hledger tools easily.
How to configure this depends on your platform and shell.
If you are using bash, this will show it:
and here's a way to add the stack and cabal install dirs permanently:
source ~/.bashrc
Here's how to set environment variables on Windows.
Test your installation
After a successful installation, you should be able to run the hledger tools and see the expected versions (the ones you just installed, and not any older versions that may exist somewhere else in your PATH). Eg:
hledger 1.21
$ hledger-ui --version
hledger-ui 1.21
$ hledger web --version
hledger-web 1.21
And you could see the unit tests pass (just for fun):
...
All 215 tests passed (0.12s)
Or if you have checked out the hledger source, also the functional tests:
Excluding 2 test files
Test Cases Total
Passed 694 694
Failed 0 0
Total 694 694
functest PASSED
Nicely done! Now check the Quick Start for next steps, or come to the #hledger chat where we'll gladly share tips or receive your feedback.