hledger/site/download.md

Download

Do you want to..

A. download a binary/system package ?

System packages are quickest to install, but they can be out of date or incomplete.

Windows:	Latest developer builds (appveyor builds are not up to date, no hledger-ui)
Mac:	brew install hledger (only hledger CLI is packaged)
Arch Linux:	pacman -S hledger (haskell problems are common on Arch at present)
Debian, Ubuntu:	sudo apt install hledger hledger-ui hledger-web
Fedora, RHEL:	sudo dnf install hledger
Gentoo:	sudo layman -a haskell && sudo emerge hledger hledger-ui hledger-web
Void Linux:	xbps-install -S hledger hledger-ui hledger-web hledger-api
NixOS:	nix-env -iA nixpkgs.haskellPackages.hledger \   nixpkgs.haskellPackages.hledger-ui \   nixpkgs.haskellPackages.hledger-web (problems building hledger-ui on MacOS)
Sandstorm:	hledger-web Sandstorm app -> demo - a hledger-web server in 3 clicks. (features needed)

B. build the latest release ?

Good choice! The release notes show what you'll get. Below are three ways to build hledger, in order of preference.

But first, a slight warning: the first build of a haskell application can take significant time (minutes to 1 hour), memory (eg 1G+), and disk space (eg 1G in ~/.stack or ~/.cabal). On the upside, it can be left unattended, you can kill and restart it without losing progress, and subsequent builds will be quicker.

Some known build issues and workarounds:\ [freebsd 12 no cabal file found](https://github.com/simonmichael/hledger/issues/709)\ [openbsd 6 exec permission denied](https://deftly.net/posts/2017-10-12-using-cabal-on-openbsd.html)\ [openbsd how to get stack](https://github.com/commercialhaskell/stack/issues/2822#issuecomment-318892816)\

1. hledger-install

On supported POSIX systems - GNU/linux, mac, freeBSD (might work on other BSDs if you install cabal-install first), possibly unixlike environments on windows - our hledger-install.sh is the build method most likely to just work:

• it requires only that you have bash and curl (or wget) installed, and internet access.
• it uses haskell build tools like stack, cabal and GHC, installing stack/GHC if needed (in ~/.stack).
• it avoids common pitfalls, such as unreliable build plans and all-or-nothing builds
• it installs the latest release of hledger and the full suite of addon tools (in ~/.local/bin or ~/.cabal/bin).

Here's the quick, non-secure way to run it:

curl https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh | bash

And here's the safer, more responsible way:

curl -O https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh
less hledger-install.sh # do security review
bash hledger-install.sh # or bash -x, to log commands

If you see link errors, you might need to manually install some extra C libraries and try again. See "Install required C libraries" below.

If you have any other trouble, you can help greatly by capturing a debug log and sending it to me via paste & IRC, an issue, or email:

bash -x hledger-install.sh 2>&1 | tee hledger-install.log

2. stack

stack is the newer and easier of the two Haskell build tools. Here's how to use it directly to install hledger:

1. Install or upgrade to the latest stack
   The latest version of stack (1.6.3+) is recommended, as it is the best at avoiding ecosystem breakages and most likely to just work. If you can get at least stack 1.3 installed, eg from your system packages, you can usually run stack upgrade to quickly upgrade it to the latest. On Windows, the 64-bit version of stack is recommended.

   Follow stack's advice to add ~/.local/bin to your $PATH (%APPDATA%\local\bin on Windows). Eg, if you're a bash user:
     echo "export PATH=$PATH:~/.local/bin" >> ~/.bashrc && source ~/.bashrc

2. Install required C libraries
   You might need to manually install some extra C libraries required by hledger's dependencies. If you're not sure about this, proceed with the next step and return here if you get link errors (for example: "/bin/ld.gold: error: cannot find -ltinfo").

   In particular the "-devel" packages for libstdc++ (for hledger-iadd), ncurses (for hledger, hledger-ui), and zlib (for hledger-web) are often required. Eg:

   Centos:	sudo yum install -y libstdc++-devel ncurses-devel zlib-devel # ⚠ still having trouble with libstdc++
   Debian, Ubuntu:	sudo apt install -y libncurses5-dev ...
   Fedora, RHEL:	sudo dnf install -y ncurses-devel ...

   (Please send us updates for the above list.)

3. stack install --resolver=nightly hledger-lib-1.5 hledger-1.5 [hledger-ui-1.5] [hledger-web-1.5] [hledger-api-1.5]\
   This installs the specified hledger packages (and required haskell libraries and tools) from Stackage (and if needed, Hackage). Specifying stackage's nightly resolver (snapshot) requires the most rebuilding, but is the most reliable; you can try reducing build time by specifying another resolver that you've installed from previously, or no --resolver option.
   Add --dry-run to see the build plan. You can kill and restart this without losing progress.

   The bracketed packages are optional; if you include them, don't type the brackets, and do always include the preceding hledger-lib and hledger packages in the command, otherwise stack may complain. (hledger-ui is not yet available on Windows, alas.)

Now you should be able to run hledger --version (and hledger-ui --version, hledger-web --version etc. if installed) and see the latest version number. Additional add-on commands, such as hledger-diff, hledger-iadd, hledger-interest, and hledger-irr can be installed similarly to the above. Eg:
  stack install --resolver nightly hledger-lib-1.5 hledger-1.5 hledger-iadd-1.3.1

3. cabal

cabal is the other Haskell build tool. If you're a cabal expert, feel free to use this instead.

C. build the development version ?

Also a good choice. Our master branch is kept stable enough for daily use, and includes the very latest improvements (commits).

1. Install stack and git
2. git clone https://github.com/simonmichael/hledger
3. cd hledger
4. stack install [hledger] # optionally specify just the hledger package to build less

cabal users may find the cabal-install.sh or cabal.project files useful.