12 KiB
Installation
GHCup makes it easy to install specific versions of GHC on GNU/Linux, macOS (aka Darwin), FreeBSD and Windows and can also bootstrap a fresh Haskell developer environment from scratch. It follows the UNIX philosophy of do one thing and do it well. Similar in scope to rustup, pyenv and jenv.
How to install
The following commands will download the ghcup binary into ~/.ghcup/bin (or C:\ghcup\bin on windows) and then
run it to interactively install the Haskell Toolchain. These commands should be run as non-root/non-admin
user.
For Linux, macOS, FreeBSD or Windows Subsystem 2 for Linux, run this in a terminal:
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
For Windows, run this in a PowerShell session:
Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;Invoke-Command -ScriptBlock ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -ArgumentList $true
There's also a youtube video explaining installation on windows.
If you want to know what these scripts do, check out the source code at the repository. Advanced users may want to perform a manual installation and GPG verify the binaries.
Which versions get installed?
GHCup has two main channels for every tool: recommended and latest. By default, it installs recommended.
latest follows the latest release of every tool, while recommended is at the discretion of the GHCup maintainers and based on community adoption (hackage libraries, tools like HLS, stackage support, etc.) and known bugs.
Also see tags and shortcuts for more information.
System requirements
Linux Debian
The following distro packages are required: build-essential curl libffi-dev libffi6 libgmp-dev libgmp10 libncurses-dev libncurses5 libtinfo5
Linux Ubuntu
The following distro packages are required: build-essential curl libffi-dev libffi6 libgmp-dev libgmp10 libncurses-dev libncurses5 libtinfo5
Linux Fedora
The following distro packages are required: gcc gcc-c++ gmp gmp-devel make ncurses ncurses-compat-libs xz perl
Linux CentOS
The following distro packages are required: gcc gcc-c++ gmp gmp-devel make ncurses ncurses-compat-libs xz perl
Linux Alpine
The following distro packages are required: binutils-gold curl gcc g++ gmp-dev libc-dev libffi-dev make musl-dev ncurses-dev perl tar xz
Linux (generic)
You need the following packages: curl g++ gcc gmp make ncurses realpath xz-utils. Consult your distro documentation on the exact names of those packages.
Darwin
On OS X, in the course of running ghcup you will be given a dialog box to install the command line tools. Accept and the requirements will be installed for you. You will then need to run the command again. On Darwin M1 you might also need a working llvm installed (e.g. via brew) and have the toolchain exposed in PATH.
FreeBSD
The following distro packages are required: curl gcc gmp gmake ncurses perl5 libffi libiconv
Windows
On Windows, msys2 should already have been set up during the installation, so most users should just proceed. If you are installing manually, make sure to have a working mingw64 toolchain and shell.
Next steps
- Follow the First steps guide on how to build a "Hello world" program, use
ghc, run an interactive REPL and create a Haskell project - To understand the difference and overlap of
stackandcabal, read on here - To learn Haskell proper check out the links at How to learn Haskell proper
- To learn more about Haskell Toolchain management, check out the ghcup user guide
Uninstallation
On linux, just run ghcup nuke, then make sure any ghcup added lines in your ~/.bashrc (or similar) are removed.
On windows, right click on the Uninstall Haskell.ps1 PowerShell script on your Desktop and select Run with PowerShell.
Supported tools
GHCup supports the following tools, which are also known as the Haskell Toolchain:
Show all supported GHC versions
| GHC Version | Tags |
|---|---|
| 9.4.3 | latest, base-4.17.0.0 |
| 9.4.2 | base-4.17.0.0 |
| 9.4.1 | base-4.17.0.0 |
| 9.2.5 | recommended, base-4.16.4.0 |
| 9.2.4 | base-4.16.3.0 |
| 9.2.3 | base-4.16.2.0 |
| 9.2.2 | base-4.16.1.0 |
| 9.2.1 | base-4.16.0.0 |
| 9.0.2 | base-4.15.1.0 |
| 9.0.1 | base-4.15.0.0 |
| 8.10.7 | base-4.14.3.0 |
| 8.10.6 | base-4.14.3.0 |
| 8.10.5 | base-4.14.2.0 |
| 8.10.4 | base-4.14.1.0 |
| 8.10.3 | base-4.14.1.0 |
| 8.10.2 | base-4.14.1.0 |
| 8.10.1 | base-4.14.0.0 |
| 8.8.4 | base-4.13.0.0 |
| 8.8.3 | base-4.13.0.0 |
| 8.8.2 | base-4.13.0.0 |
| 8.8.1 | base-4.13.0.0 |
| 8.6.5 | base-4.12.0.0 |
| 8.6.4 | base-4.12.0.0 |
| 8.6.3 | base-4.12.0.0 |
| 8.6.2 | base-4.12.0.0 |
| 8.6.1 | base-4.12.0.0 |
| 8.4.4 | base-4.11.1.0 |
| 8.4.3 | base-4.11.1.0 |
| 8.4.2 | base-4.11.1.0 |
| 8.4.1 | base-4.11.0.0 |
| 8.2.2 | base-4.10.1.0 |
| 8.0.2 | base-4.9.1.0 |
| 7.10.3 | base-4.8.2.0 |
Show all supported cabal-install versions
| Cabal Version | Tags |
|---|---|
| 3.8.1.0 | latest |
| 3.6.2.0 | recommended |
| 3.6.0.0 | |
| 3.4.1.0 | |
| 3.4.0.0 | |
| 3.2.0.0 | |
| 3.0.0.0 | |
| 2.4.1.0 |
Show all supported HLS versions
| HLS Version | Tags |
|---|---|
| 1.8.0.0 | latest, recommended |
| 1.7.0.0 | |
| 1.6.1.0 | |
| 1.6.0.0 | |
| 1.5.1 | |
| 1.5.0 | |
| 1.4.0 | |
| 1.3.0 | |
| 1.2.0 | |
| 1.1.0 |
Show all supported Stack versions
| Stack Version | Tags |
|---|---|
| 2.9.1 | latest, recommended |
| 2.7.5 | |
| 2.7.3 | |
| 2.7.1 | |
| 2.5.1 |
Supported platforms
This list may not be exhaustive and specifies support for bindists only.
| Platform | Architecture | ghcup | GHC | cabal | HLS | stack |
|---|---|---|---|---|---|---|
| Windows 7 | amd64 | ❔ | ✅ | ✅ | ✅ | ✅ |
| Windows 10 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows Server 2016 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows Server 2019 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows Server 2022 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows WSL1 | amd64 | ❌ | ❔ | ❔ | ❔ | ❔ |
| Windows WSL2 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| MacOS >=10.13 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| MacOS <10.13 | amd64 | ❌ | ❔ | ❔ | ❔ | ❔ |
| MacOS | aarch64 | ✅ | ✅ | ✅ | ⚠️ | ❌ |
| FreeBSD | amd64 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
| Linux generic | x86 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux generic | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux generic | aarch64 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
| Linux generic | armv7 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
Windows 7
May or may not work, several issues:
- https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/140
- https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/197
WSL1
Unsupported. GHC may or may not work. Upgrade to WSL2.
MacOS <10.13
Not supported. Would require separate binaries, since >=10.13 binaries are incompatible. Please upgrade.
MacOS aarch64
HLS bindists are still experimental. Stack has only unofficial binaries for this platform. There are various issues with GHC itself.
FreeBSD
Lacks some upstream bindists and may need compat libs, since most bindists are built on FreeBSD-12. HLS bindists are experimental.
Linux ARMv7/AARCH64
Lower availability of bindists. Stack and HLS binaries are experimental.
Manual installation
Download the binary for your platform at https://downloads.haskell.org/~ghcup/
and place it into your PATH anywhere.
If you want to GPG verify the binaries, import the following keys first: 7784930957807690A66EBDBE3786C5262ECB4A3F and FE5AB6C91FEA597C3B31180B73EDE9E8CFBAEF01.
Then adjust your PATH in ~/.bashrc (or similar, depending on your shell) like so:
export PATH="$HOME/.cabal/bin:$HOME/.ghcup/bin:$PATH"
Vim integration
See ghcup.vim.
VSCode integration
The developers of the Haskell Language Server offer an extension tightly integrated with the Haskell Language Server. To get started:
- Install GHCup. During installation, opt in to install the Haskell Language Server (HLS).
- Install the extension (from VSCode: Ctrl + P and then
ext install haskell.haskell). - Make sure your project uses the GHC version installed from GHCup (otherwise HLS is likely to fail on launch):
- instructions for stack
On Linux, some users have reported an issue when VSCode is not launched from a terminal ("cannot find ghc version"). A solution is to let HLS know about your GHCup on $PATH.