The Haskell Tool Stack¶
Welcome to the Haskell programming language and the Haskell Tool Stack (Stack)! Stack is a program for developing Haskell projects. It is aimed at Haskellers both new and experienced. It is cross-platform and aims to support fully users on Linux, macOS and Windows.
- Installing the Glasgow Haskell Compiler (GHC) automatically, in an isolated location.
- Installing packages needed for your project.
- Building your project.
- Testing your project.
- Benchmarking your project.
How to install Stack¶
Stack can be installed on most Unix-like operating systems (including macOS) and Windows.
In addition to the methods described below, Stack can also be installed using the separate GHCup installer for Haskell-related tools. GHCup provides Stack for some combinations of machine architecture and operating system not provided elsewhere. By default, the script to install GHCup (which can be run more than once) also configures Stack so that if Stack needs a version of GHC, GHCup takes over obtaining and installing that version.
For most Linux distributions, the easiest way to install Stack directly (rather than use GHCup) is to command:
The script at get.haskellstack.org will
ask for root access using
sudo. It needs such access in order to use
your platform's package manager to install dependencies and to install
/usr/local/bin. If you prefer more control, follow the manual
installation instructions in the
install and upgrade guide.
From late 2020, Apple began a transition from Mac computers with Intel processors (Intel-based Mac) to Mac computers with Apple silicon.
For most Intel-based Mac computers, the easiest way to install Stack directly (rather than use GHCup) is to command:
The script at get.haskellstack.org
will ask for root access using
sudo. It needs such access in order
to use your platform's package manager to install dependencies and
to install to
/usr/local/bin. If you prefer more control, follow
the manual installation instructions in the
install and upgrade guide.
Mac computers with Apple silicon have an M1, M1 Pro, M1 Max, M1 Ultra or M2 chip. These chips use an architecture known as ARM64 or AArch64.
For Mac computers with Apple silicon, the easiest way to install Stack
directly (rather than use GHCup) is to obtain the 'unofficial'
osx-aarch64 binary distribution released by the GHCup developers and
copy it to a location on the PATH.
*.tar.gz archive files containing
those binary distributions are available at the directories here:
It is still possible to use the commands:
However, those commands will download and install the version of Stack for Intel-based Mac computers. Mac computers with Apple silicon will use Apple's Rosetta 2 application to use that version of Stack.
Apple's Terminal application will not detect automatically that Rosetta has not yet been installed. Rosetta can be manually installed by commanding:
On 64-bit Windows, the easiest way to install Stack directly (rather than use GHCup) is to download and install the Windows installer.
Systems with antivirus software may need to add Stack to the list of 'trusted' applications.
For other operating systems and direct downloads (rather than use GHCup), see the install and upgrade guide.
How to upgrade Stack¶
If Stack is already installed, you can upgrade it to the latest version by the command:
If you used GHCup to install Stack, you should also use GHCup, and not Stack, to upgrade Stack.
Quick Start guide¶
For an immediate experience of using Stack to build an executable with Haskell, first you need to follow the guide to install Stack.
Step 1: Start your new project¶
To start a new project named
my-project, issue these four commands in a
stack new my-projectcommand will create a new directory, named
my-project. It contains all the files needed to start a project correctly, using a default template.
cd my-projectcommand will change the current working directory to that directory.
stack buildcommand will build the template project and create an executable named
my-project-exe.exe). First, if necessary, Stack will download a version of GHC in an isolated location. That won't interfere with other GHC installations on your system.
stack exec my-project-execommand will run (execute) the built executable, in Stack's environment.
For a complete list of Stack's commands, and flags and options common to those commands, simply command:
For help on a particular Stack command, including flags and options specific to
that command, for example
stack build, command:
If you want to launch a run-eval-print loop (REPL) environment, then command:
stack ghci can be used instead of
stack repl. GHCi is GHC's REPL tool.
People organise Haskell code into packages. If you want to use Stack to install an executable provided by a Haskell package, then all you have to do is command:
Step 2: Next steps¶
stack new my-project command in step one should have created the following
files and directories (among others):
. ├── app │ └── Main.hs ├── src │ └── Lib.hs ├── test │ └── Spec.hs ├── my-project.cabal ├── package.yaml └── stack.yaml
The Haskell source code for the executable (application) is in file
The executable uses a library. Its source code is in file
The contents of
my-project.cabal describes the project's package. That file is
generated by the contents of
If you want, you can delete the
package.yaml file and update the
my-project.cabal file directly. Stack will then use that file.
The contents of
stack.yaml describe Stack's own project-level configuration.
You can edit the source files in the
src directory (used for the library) or
app directory (used for the executable (application)).
As your project develops, you may need to depend on a library provided by
another Haskell package. If you do, then add the name of that new package to the
package.yaml, in its
When you use
stack build again, Stack will use
package.yaml to create an
my-project.cabal for you.
If Stack reports that the Stack configuration has no specified version for the
new package, then follow Stack's likely recommended action to add a specific
version of that package your project's
stack.yaml file, in its
That was a really fast introduction on how to start to code in Haskell using Stack. If you want to go further, we highly recommend you read Stack's introductory user's guide.
Complete guide to Stack¶
A complete user's guide to Stack is available, covering all of the most common ways to use Stack. Terms used in Stack's documentation are also explained in the glossary.
Stack is a build tool for Haskell designed to answer the needs of Haskell users, both new and experienced. It has a strong focus on reproducible build plans, multi-package projects, and a consistent, easy-to-learn set of Stack commands. It also aims to provide the customizability and power that experienced developers need.
Stack does not stand alone. It is built on the great work provided by:
- The Glasgow Haskell Compiler (GHC), the premier Haskell compiler. Stack will manage your GHC installations and automatically select the appropriate version of GHC for your project.
The Cabal build system. Cabal is a specification for defining Haskell packages and a library for performing builds.
Cabal is also the name of another build tool, provided by the
cabal-installpackage. This guide distinguishes between them by Cabal (the library) and Cabal (the tool).
The Hackage Haskell Package Repository, a repository of Haskell packages providing thousands of open source libraries and applications to help you get your work done.
- The Stackage package collection, sets of packages from Hackage that are curated. That is, they are regularly tested for compatibility. Stack defaults to using Stackage package sets to avoid problems with incompatible dependencies.
Stack is provided by a team of volunteers and companies under the auspices of the Commercial Haskell group. The project was spearheaded by FP Complete to answer the needs of commercial Haskell users. It has since become a thriving open source project meeting the needs of Haskell users of all stripes.
If you'd like to get involved with Stack, check out the newcomer friendly label on the GitHub issue tracker.
Questions, feedback, and discussion¶
- For answers to frequently asked questions about Stack, please see the FAQ.
- For general questions, comments, feedback and support, please post to the Haskell Community.
- For bugs, issues, or requests, please open an issue.
- When using Stack Overflow, please use the haskell-stack tag.
How to contribute to the maintenance or development of Stack¶
The following assumes that you already have installed a version of Stack and the Git application.
stackrepository from GitHub with the command:
Change the current working directory to the cloned
stackdirectory with the command:
stackexecutable using a preexisting installation of Stack with the command:
stackexecutable has been built, check its version with the command:
Make sure the version is the latest one.
In the GitHub repository's issue tracker, look for issues tagged with newcomer friendly and awaiting pull request labels.
If you need to check your changes quickly command:
and then, at the REPL's prompt, command:
This allows you to set a special Stack root (instead of the default Stack root)
and to target your commands at a particular
stack.yaml file instead of the one
found in the current directory.
How to uninstall¶
To uninstall Stack, it should be sufficient to delete:
- the Stack root directory (see
stack path --stack-root, before you uninstall);
- if different, the directory containing Stack's global YAML configuration file
stack path --global-config, before you uninstall);
- on Windows, the directory containing Stack's tools (see
stack path --programs, before you uninstall), which is located outside of the Stack root directory; and
stackexecutable file (see
which stack, on Unix-like operating systems, or
where.exe stack, on Windows).
You may also want to delete
.stack-work directories in any Haskell projects
that you have built using Stack. The
stack uninstall command provides
information about how to uninstall Stack.