--- title: Getting started ---
# Getting started Stack is a program for developing [Haskell](https://www.haskell.org/) projects. You may be getting started with Haskell or you may only be getting started with Stack. If you are getting started with Haskell, you may already know other programming languages or you may be new to coding. This guide is aimed at people getting started with Stack. It takes a new Stack user through the ways that Stack is typically used. It requires no prior experience of Stack or other Haskell tools. This guide will not teach Haskell - other resources are better placed to do that - or involve much code. However, it does aim to be accessible to people who who are relatively inexperienced in coding with Haskell. Terms used in the guide will be explained as they are introduced and are also defined in the [glossary](../glossary.md). Some of Stack's features will not be needed regularly or by all users. Other parts of Stack's documentation include its [commands](../commands/index.md) and its [configuration](../configure/index.md). ## Other Haskell tools First, simplifying greatly, let us briefly place Stack and other Haskell tools in the Haskell landscape. Haskell was specified in the [Haskell 98 Language and Library Reports](https://www.haskell.org/onlinereport/), first published in February 1999, and further specified in the [Haskell 2010 Language Report](https://www.haskell.org/onlinereport/haskell2010/), published in April 2010. Extensions to the language have been developed (see below). The Haskell compiler is **GHC** (the [Glasgow Haskell Compiler](https://www.haskell.org/ghc/)). It can compile Haskell code into executable and other binary files. GHC can also be used interactively (**GHCi**) and Stack supports such use. ~~~mermaid flowchart LR code@{ shape: docs, label: "Haskell code" } ghc[GHC] binaries@{ shape: docs, label: "Executable and other binary files" } code --> ghc --> binaries ~~~ A lot of interesting things can be done using only what comes with GHC (including GHCi) but as Haskell code becomes more complex and there is a desire to reuse efficiently code developed by others it becomes necessary to organise code in a structured way. In that regard, Haskell code can be organised into *packages*. A Haskell package also includes a file that describes the package's contents. The most established description format is known as a [Cabal file](https://cabal.readthedocs.io/en/stable/file-format-changelog.html). The [**Hpack** project](https://github.com/sol/hpack) provides a modern alternative format (in a file named `package.yaml`) and a library and application that translates from that format to the legacy format. Stack has built-in support for Hpack. Other build tools (see below) do not. ~~~mermaid flowchart LR packageYaml@{ shape: doc, label: "package.yaml" } hpack[Hpack] cabalFile@{ shape: doc, label: "Cabal file" } packageYaml --> hpack --> cabalFile ~~~ The code in a Haskell package is organised into *components*, including components known as *libraries*. Historically, a package had no more than one library component. The Cabal specification has developed to allow a package to have named *sub-library* components as well as a main library. The code in a Haskell package can depend on the libraries in the same package or in another package. These are known as its *dependencies*. GHC comes with the libraries of certain Haskell packages (known as *boot packages*) already installed in its global database of installed libraries. These include the library of the [package `base`](https://hackage.haskell.org/package/base), which is a dependency of almost all other packages, and the library of [package `Cabal`](https://hackage.haskell.org/package/Cabal), which provides code to build packages and components of packages using GHC. Two important public databases are **Hackage** [(the Haskell Package Repository)](https://hackage.haskell.org/) and [**Stackage**](https://www.stackage.org/). ~~~mermaid flowchart LR hackage@{ shape: lin-cyl, label: "Hackage (packages)" } stackage@{ shape: lin-cyl, label: "Stackage (snapshots)" } hackage --> stackage ~~~ Hackage is a database of Haskell packages, each identified by a name and version number. There were over 17,000 package names on Hackage as at July 2025. Stackage is a database of collections of Haskell package versions on Hackage that are known, by testing, to work well together and with a specific version of GHC and its boot packages. Those collections are known as *snapshots*. As at July 2025, a snapshot for a recent version of GHC includes well over 3,000 packages. Stack can unpack packages from, and upload packages to, Hackage and builds making use of snapshots from Stackage. GHC comes with an application [**Haddock**](https://haskell-haddock.readthedocs.io/latest/) that automatically generates web page and other documentation from annotated Haskell code. The Hackage and Stackage websites display that documentation. Stack supports the use of Haddock. ~~~mermaid flowchart LR code@{ shape: docs, label: "Haskell code" } haddock[Haddock] docs@{ shape: docs, label: "Documentation" } code --> haddock --> docs ~~~ **Hoogle** is a [website](https://hoogle.haskell.org/) and an [application](https://hackage.haskell.org/package/hoogle) that allows its users to search for the library components of Haskell packages, the modules they expose, and functions and types exported by modules. Stack supports the use of Hoogle on the command line. GHC is described in its [User Guide](https://downloads.haskell.org/ghc/latest/docs/users_guide/). It can be used directly but it is a complex application with many flags and options. These include flags to specify extensions to the Haskell language. Haskell *build tools* are applications that make it easier to use GHC, including by applying sensible defaults. Stack is such a build tool. Stack itself uses the Cabal library to build. ~~~mermaid flowchart LR stack[Stack] cabal["Cabal (the library)"] code@{ shape: docs, label: "Haskell code" } ghc[GHC] binaries@{ shape: docs, label: "Executable and other files" } subgraph buildtool ["Build tool"] direction TB stack --> cabal --> ghc end code --> buildtool --> binaries ~~~ When Haskell code changes, GHC and build tools aim to minimise what needs to be re-compiled. A Stack project may comprise only a single package, but Stack can also handle multi-package projects. Another build tool is **Cabal** (the tool) (named after the library). It is provided by the [`cabal-install`](https://hackage.haskell.org/package/cabal-install) Haskell package. Stack can be used independently of Cabal (the tool) but users can also use both, if they wish. Some popular code editors (including [Visual Studio Code](https://code.visualstudio.com/)) have extensions that support Haskell coding by providing an integrated development environment (IDE). Those extensions use **HLS** (the [Haskell Language Server](https://haskell-language-server.readthedocs.io/en/stable/)), an application that implements the Language Server Protocol for Haskell. Stack can manage versions of GHC and upgrade/downgrade Stack itself and is, in that sense, an *installer* of those applications as well as a build tool. However, Cabal (the tool) is not an installer and versions of HLS applicable to versions of GHC also need to be installed. [**GHCup**](https://www.haskell.org/ghcup/) is an installer of versions of GHC, HLS, Stack and Cabal (the tool) built for various operating systems and machine architectures. Stack can be configured to manage versions of GHC by using GHCup. ~~~mermaid flowchart TD ghcUp["GHCup installer"] ghc["GHC compiler"] hls["HLS IDE tool"] stack["Stack build tool, installer"] cabal["Cabal (the tool) build tool"] ghcUp -.-> ghc ghcUp -.-> hls ghcUp -.-> stack stack -- "(optional) to fetch GHC" --> ghcUp ghcUp -.-> cabal ~~~ ## Setting up The goal of setting up is a `stack` executable on the PATH. As we will see, when Stack is used, it sets other things up as needed. *[PATH]: An environment variable that specifies a list of directories searched for executable files. For further information about setting up, see the [documentation](../install_and_upgrade.md) on that topic. Return here when you know that Stack is on the PATH. This guide assumes that the directory where Stack install executables (the location reported by `stack path --local-bin`) has been added to the PATH. This guide assumes that your computer's operating system is one of Linux, macOS or Windows. Stack's commands are the same on all operating systems.