Install
The current hledger release is 1.25. (Release notes)
Here are lots of ways to install hledger - choose one that suits your needs. Binary packages install quickly but are not always up to date (look for green badges). Building from source is slower and requires at least 4G of ram.
After installing, please check your PATH, locale, and installation, and share any feedback so we can make this process smoother!
Binary packages
Mac
brew install hledger
|
Windows
choco install hledger -y
|
GNU/Linux
sudo layman -a haskell && sudo emerge hledger hledger-ui hledger-web
|
|
pacman -Sy hledger hledger-ui hledger-web
|
|
sudo apk add hledger hledger-ui hledger-web
|
|
xbps-install -S hledger hledger-ui hledger-web
|
|
sudo dnf install hledger
|
|
sudo apt install hledger hledger-ui hledger-web
|
|
sudo apt install hledger hledger-ui hledger-web
|
Raspberry Pi
|
|
|
Note: unaudited third party binaries
|
BSD
pkg_add hledger
|
|
pkg_add hledger
|
|
pkg install hs-hledger hs-hledger-ui hs-hledger-web
|
Other
docker pull dastapov/hledger
|
|
nix-env -f https://github.com/NixOS/nixpkgs/archive/e1225076.tar.gz -iA hledger_1_24_1 hledger-ui_1_24_1 hledger-web_1_24_1
|
|
|
Preview releases
|
Previews of the next major release, for testers & early adopters.
|
Building the current release
You can build hledger from its source code on any machine with GHC and sufficient RAM (4G recommended) and disk space (up to 2G for a first build). Including all dependencies, this could take anywhere from a minute to an hour.
With hledger-install
This is a good choice if you are new to Haskell and its build tools. On any machine with bash (and possibly make, gcc...): download and run the hledger-install.sh script to build the current release of the hledger tools, plus some add-ons, in a relatively reliable way. It will use either stack or cabal if you have them, or will install stack in ~/.local/bin if needed, and it installs the hledger tools in ~/.local/bin or ~/.cabal/bin respectively.
less hledger-install.sh # <- good practice: inspect downloaded scripts before running
bash hledger-install.sh
With stack
If you have stack, you can run it yourself to install the main hledger tools in ~/.local/bin:
stack install --resolver=lts-18 hledger-lib-1.25 hledger-1.25 hledger-ui-1.25 hledger-web-1.25 --silent
Your stack --version
should be modern (at least 2.7) for best results.
(You can usually upgrade stack quickly with stack upgrade
.)
On Windows, prefer the 64-bit version of stack,
and omit hledger-ui from this command (unless you are in WSL).
With cabal
If you have GHC and cabal, you can run cabal yourself to install the main hledger tools in ~/.cabal/bin:
cabal install alex happy
cabal install hledger-1.25 hledger-ui-1.25 hledger-web-1.25
Your cabal --version
should be modern (at least 3.2) for best results.
On Windows, omit hledger-ui from this command (unless you are in WSL).
With nix
If you have nix, you can use nix-env to build hledger from source (but we try to provide a nix command that installs already-cached binaries, see above).
C libraries required
On some unix systems, certain required C libraries may not be installed. So if you see errors like "cannot find -ltinfo" when building hledger, install them with a command like the below and try again:
Debian, Ubuntu & co.: |
sudo apt install libtinfo-dev libgmp-dev zlib1g-dev |
Fedora, RHEL: |
sudo dnf install gmp-devel ncurses-devel |
(Please send updates for this list.)
UTF-8 locale required
On unix systems, when building hledger the LANG
environment variable
must be set to a UTF-8-aware locale. See Check your locale.
Other build tips
-
You can use less resources by omitting hledger-ui and hledger-web from the commands above.
-
On machines with less than 4G of RAM, the build may use swap space and take a very long time (overnight), or it may die. Try adding
-j1
to the stack/cabal install command, and retry a few times, or ask for help. -
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 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 platform-specific build issues and workarounds:
mac m1: building with ghc 9+ requires extra include dir
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
or you can build in a Docker container which includes 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.)
Pre-flight checks
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 , if you are a bash user:
source ~/.bashrc
Here's how to set environment variables on Windows.
Check your locale
On unix systems, when running hledger
(and other GHC-compiled programs, like GHC, cabal & stack),
the LANG
environment variable must be set to a UTF-8-aware locale
to avoid errors like "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.
Check 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.25-gd60ebcbd6-20220304, mac-x86_64
$ hledger-ui --version
hledger-ui 1.25-gd60ebcbd6-20220304, mac-x86_64
$ hledger web --version
hledger-web 1.25-gd60ebcbd6-20220304, mac-x86_64
And you could see the unit tests pass (just for fun):
...
All 223 tests passed (0.13s)
Or if you have checked out the hledger source, also the functional tests:
...
Total 872 ...
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.