The purpose of this section is to provide generic, step-by-step instructions for installing Haskell. These instructions are project agnostic. Reference the project developer guide and/or user guide for specific instructions.
Three applications will be installed: GHCup, GHC and Cabal. GHCup is a utility for installing applications in the Haskell toolchain. GHC is a Haskell compiler. Cabal is a system for building and packaging Haskell code.
If you are using a Windows system then you may be queried at various times during or after the installation process as to whether the system’s virus protection application should allow a given application to run. Please select "Allow" for any such queries. Also see Command not found/recognized error message (Windows specific) for troubleshooting problems related to virus protection systems.
If you receive error messages at any point during setup, please consult the Troubleshooting section.
Open a terminal and point to your home directory.
In your terminal, run the command provided to you at the GHCup landing page.
If using Windows OS, when prompted with Where to install to (this should be a short Path, preferably a drive like 'C:\') input the appropriate path (using the suggested default will likely be fine).
If using Windows OS, when prompted with Specify Cabal directory (this is where haskell packages end up) input the appropriate path (using the suggested default will likely be fine).
If using a Unix-like system, when prompted with Do you want ghcup to automatically add the required PATH variable to your shell startup file? select "Yes, prepend".
When prompted with Do you want to install haskell-language-server (HLS)? select "Yes".
When prompted with Do you want to install stack? see the specific setup instructions for your project(s). If the projects you will be working on use Cabal, then Stack is not needed (though there is no harm in installing it).
If using Windows OS, when prompted with Do you want GHCup to install a default MSys2 toolchain? select "Yes" unless you already MSys2 installed.
After installation finishes, restart your terminal.
Check that GHCup installed correctly by typing
ghcup --help. If the command is not recognized, check the Troubleshooting section first. If there are still issues, request help in the techsupport Slack channel.
Installing individual toolchain components
You will have likely installed each of the following toolchain components as part of the GHCup installation. However, you may at some point want to install a different version of one of those components. If that is the case then the following are the instructions for installing those components. It is worth noting that even if you have a particular version of a given component installed then there is no harm in asking GHCup to install it again because it will be smart enough to essentially make it a no-operation the second time around.
The version to install is project-specific, but likely 8.10.7. To determine the version of GHC to install for your project consult the
cabal.projectfile (for Cabal projects), or if it’s not specified there then it could be also be mentioned in the
.gitlab-ci.ymlfile in the project repository. If you are working on multiple projects, then you may need to install multiple versions of GHC.
Once the appropriate version has been determined, type
ghcup install ghc <VERSION>in the terminal and press Enter.
Verify that ghc has been installed by typing
ghc-<VERSION> --help. If the command is not recognized, check the Troubleshooting section first. If there are still issues, contact a member of the stats dev team for help.
ghcup install cabal 184.108.40.206in the terminal and press Enter.
Verify that cabal has been installed by typing
cabal-220.127.116.11 --help. If the command is not recognized, check the Troubleshooting section first. If there are still issues, contact a member of the stats dev team for help.
HLS installation. Usually you will want to install whatever the recommended version of HLS is according to
ghc install hlsin your terminal and press Enter.
If you receive the error message below:
<no location info>: error: Warning: Couldn't figure out LLVM version! Make sure you have installed LLVM between [9 and 13)
then you need to install a different build of LLVM.
If you have Homebrew installed, you can run the code below
brew install llvm
If you are not a Homebrew user, check the LLVM website for alternative installation instructions.
You will also want to add the following line,
amended to include the appropriate path,
to your shell startup file:
After adding the above line (potentially with the appropriate modifications) restart your shell. Also see Ensuring applications are on the search path for more specific instructions regarding regarding shell search paths.
Also see Help wanted for LLVM config for Haskell on Mac on Reddit for some additional discussion.
If you attempt to run
<APPLICATION NAME> --help,
where the APPLICATION NAME is
and you get an error message like the following,
it is possible that you are running the command in MinGW or WSL.
Please try the command in PowerShell instead.
bash: ghc: command not found
suppose you attempt to run
<APPLICATION NAME> --help in PowerShell
and get an error message like the following.
ghc : The term 'ghc' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
First, ensure that you have restarted PowerShell since you performed the installation.
Next, check the
bin folder in your GHCup installation directory;
this will often default to
This folder should contain files like
If the GHCup
binfolder doesn’t exist or doesn’t contain a collection of files like the ones described above, then there was likely a problem with the application installation and you may want to wipe everything clean and retry the installation.
Next, check that GHCup
binfolder is on your search path. Enter
$Env:Pathinto PowerShell and ensure that you see the appropriate GHCup bin folder in the output.
If the GHCup
binfolder does exist and is on the search path, then you may need to whitelist the application you are trying to run with your virus protection application. In some cases the virus protection application may even delete the application. In that case you may see that you have
<APPLICATION NAME>.shimbut no
<APPLICATION>file. The process for whitelisting files will depend on your particular system’s virus protection application; Please see the corresponding documentation for details.
Many of the applications in the Haskell toolchain rely on being on the shell’s search path,
which is a list of directories in which applications are looked for.
This list is defined by the
PATH variable for most commonly-used shells.
To ensure that the applications installed by e.g. GHCup are on the search path,
the directories in which the applications are installed into are usually added to the
PATH variable as part of a so-called startup file which is processed whenever the shell is first invoked.
To check what directories are listed on your search path,
echo $PATH in your shell and you should see a string of colon-separated directories.
For example, if you are on a macOS system then you should see entries similar to
and possibly an entry similar to
/opt/homebrew/opt/llvm/bin in the event that you needed to install a different version of LLVM.
If the appropriate directories are not in your current search path, try the following troubleshooting steps.
Try opening a new shell to ensure that your shell has read in the most recent version of the startup files.
Ensure that the required directories are added to the
PATHvariable in your startup files.
Check which shell you are using by running the command
ps -p $$.
Check that the appropriate directories are added to one of the startup files for your shell.
If you are a Bash user then check
~/.bashrc(or whichever file you put them in)
If you are a Z shell user then check
~/.zshrc(or whichever file you put them in).
The entries should be of the form
export PATH="/Users/username/.ghcup/bin:$PATH"(the paths will by system and username specific).
Ensure that the
SHELLvariable corresponds to the shell that you are using.
echo $SHELLto display the value of
If you are a Bash user and
SHELLisn’t appropriately set then run the command
chsh -s /bin/bash.
If you are a Z shell user and
SHELLisn’t appropriately set then run the command
chsh -s /bin/zsh.
Ensure that the application you are using to launch the shell is configured to launch the appropriate shell. Many applications use the value of
SHELLto determine which shell to use, but if that isn’t working you can often specify the desired shell. To configure VSCode’s terminal see the Integrated Terminal instructions.
If you receive an error with a message like the following:
curl: (60) SSL certificate problem: self signed certificate in certificate chain
please try the following workarounds:
Upgrade the version of curl. If you run
curl --versionand it lists an old release date, then you may want to install a newer version. You can see when your version of curl was released by viewing the curl - Release web page.
Update your OpenSSL certificates. If you installed OpenSSL on macOS through Homebrew, then you can use the command
brew postinstall openssl. If you did not use Homebrew, you can install OpenSLL from source.
Use wget instead of curl when running GHCup by specifying the option
--downloader=wget. So for example, you can use the command
ghcup --downloader=wget list
The purpose of this section is to provide IDE-specific instructions for creating the optimal Haskell experience.
At this time, we are only providing guidance on Visual Studio Code. Other IDEs such as Emacs and Vim may be optimal for certain users, but require more configuration. We hope to include guidance on these IDEs in the future.
Visual Studio Code has many extensions to support Haskell development. The recommended extensions are listed below.
Note that haskell-linter requires some additional work.
Every extension can be configured by navigating to Code > Preferences > Settings and selecting "Extensions" from the menu. We recommend the following Settings:
Set "Formatting Provider" to "brittany"