This page is intended to fully document all configuration options available in the stack.yaml file. Note that this page is likely to be both incomplete and sometimes inaccurate. If you see such cases, please update the page, and if you're not sure how, open an issue labeled "question".
The stack.yaml configuration options break down into project-specific options in:
and non-project-specific options in:
/etc/stack/config.yaml-- for system global non-project default options
~/.stack/config.yaml-- for user non-project default options
- The project file itself may also contain non-project specific options
Note: When stack is invoked outside a stack project it will source project
specific options from
~/.stack/global-project/stack.yaml. When stack is
invoked inside a stack project, only options from
<project dir>/stack.yaml are
~/.stack/global-project/stack.yaml is ignored.
Project-specific options are only valid in the
stack.yaml file local to a
project, not in the user or global config files.
Note: We define project to mean a directory that contains a
stack.yamlfile, which specifies how to build a set of packages. We define package to be a package with a
.cabalfile or Hpack
In your project-specific options, you specify both which local packages to build and which dependencies to use when building these packages. Unlike the user's local packages, these dependencies aren't built by default. They only get built when needed.
Shadowing semantics, described
applied to your configuration. So, if you add a package to your
it will be used even if you're using a snapshot that specifies a particular
extra-deps will shadow the version specified in the
packages section lists all local (project) packages. The term local
package should be differentiated from a dependency package. A local package
is something that you are developing as part of the project. Whereas a
dependency package is an external package that your project depends on.
In its simplest usage, it will be a list of directories or HTTP(S) URLs to a tarball or a zip. For example:
packages: - . - dir1/dir2 - https://example.com/foo/bar/baz-0.0.2.tar.gz
Each package directory or location specified must have a valid cabal file present. Note that the subdirectories of the directory are not searched for cabal files. Subdirectories will have to be specified as independent items in the list of packages.
packages field is not present, it defaults to looking for a package
in the project's root directory:
packages: - .
Complex package locations (
More complex package locations can be specified in a key-value format with
location as a mandatory key. In addition to
location some optional
key-value pairs can be specified to include specific subdirectories or to
specify package attributes as descibed later in this section.
In its simplest form a
location key can have a single value in the same way
as described above for single value items. Alternativel it can have key-value
pairs as subfields to describe a git or mercurial repository location. For
packages: - location: . - location: dir1/dir2 - location: https://example.com/foo/bar/baz-0.0.2.tar.gz - location: http://github.com/yesodweb/wai/archive/2f8a8e1b771829f4a8a77c0111352ce45a14c30f.zip - location: git: firstname.lastname@example.org:commercialhaskell/stack.git commit: 6a86ee32e5b869a877151f74064572225e1a0398 - location: hg: https://example.com/hg/repo commit: da39a3ee5e6b4b0d3255bfef95601890afd80709
Note: it is highly recommended that you only use SHA1 values for a Git or Mercurial commit. Other values may work, but they are not officially supported, and may result in unexpected behavior (namely, stack will not automatically pull to update to new versions). Another problem with this is that your build will not be deterministic, because when someone else tries to build the project they can get a different checkout of the package.
location key can be accompanied by a
subdirs key to look for cabal files
in a list of subdirectories as well in addition to the top level directory.
subdirs key can have multiple nested series items specifying a list of
subdirectories. For example:
packages: - location: . subdirs: - subdir1 - subdir2 - location: git: email@example.com:yesodweb/wai commit: 2f8a8e1b771829f4a8a77c0111352ce45a14c30f subdirs: - auto-update - wai - location: http://github.com/yesodweb/wai/archive/2f8a8e1b771829f4a8a77c0111352ce45a14c30f.zip subdirs: - auto-update - wai
subdirs defaults to
['.'] (i.e. look only in the top-level
directory). Note that if you specify a value of
'.' is not
included by default and needs to be explicitly specified if a required package
is found in the top-level directory of the repository.
Local dependency packages (
location key can be accompanied by an
extra-dep key. When the
extra-dep key is set to
true it indicates that the package should be
treated in the same way as a dependency package and not as part of the project.
This means the following:
A dependency package is built only if a user package or its dependencies
depend on it. Note that a regular project package is built anyway even if
no other package depends on it.
Its test suites and benchmarks will not be run.
* It will not be directly loaded in ghci when
stack ghci is run. This is
important because if you specify huge dependencies as project packages then
ghci will have a nightmare loading everything.
This is especially useful when you are tweaking upstream packages or want to use latest versions of the upstream packages which are not yet on Hackage or Stackage.
packages: - location: . - location: vendor/binary extra-dep: true - location: git: firstname.lastname@example.org:yesodweb/wai commit: 2f8a8e1b771829f4a8a77c0111352ce45a14c30f subdirs: - auto-update - wai extra-dep: true
This is a list of package identifiers for additional packages from upstream to be included. This is usually used to augment an LTS Haskell or Stackage Nightly snapshot with a package that is not present or is at an different version than you wish to use.
extra-deps: - acme-missiles-0.3
Note that the
extra-dep attribute in the
packages section as described in
an earlier section is used for non-index local or remote packages while the
extra-deps section is for packages to be automatically pulled from an index
Specifies how dependencies are resolved. There are currently four resolver types:
- LTS Haskell snapshots, e.g.
- Stackage Nightly snapshot, e.g.
- No snapshot, just use packages shipped with the compiler
- For GHC this looks like
- For GHCJS this looks like
- For GHC this looks like
- Custom snapshot
Each of these resolvers will also determine what constraints are placed on the compiler version. See the compiler-check option for some additional control over compiler version.
Flags can be set for each package separately, e.g.
flags: package-name: flag-name: true
Flags will only affect packages in your
Packages that come from the snapshot global database are not affected.
The image settings are used for the creation of container images using
stack image container, e.g.
image: containers: - base: "fpco/stack-build" add: static: /data/static
base is the docker image that will be used to built upon. The
allow you to add additional directories to your image. You can specify the name
of the image using
name (otherwise it defaults to the same as your project).
You can also specify
entrypoints. By default all your executables are placed
/usr/local/bin, but you can specify a list using
executables to only add
When you specify
entrypoints, multiple containers will be built: a project
container, and one container for each entrypoint.
For example the following configuration:
image: containers: - name: myproject base: fpco/stack-run add: production/app-backend/conf/: /etc/app-backend entrypoints: - app-backend
will build one container tagged
myproject:latest which contains the project
/etc/app-backend configuration data.
Another container tagged
myproject-app-backend:latest based on the
will additionally contain the logic for starting the
A user-message is inserted by
stack init when it omits packages or adds
external dependencies. For example:
user-message: ! 'Warning: Some packages were found to be incompatible with the resolver and have been left commented out in the packages section. Warning: Specified resolver could not satisfy all dependencies. Some external packages have been added as dependencies. You can suppress this message by removing it from stack.yaml '
This messages is displayed every time the config is loaded by stack and serves as a reminder for the user to review the configuration and make any changes if needed. The user can delete this message if the generated configuration is acceptable.
Non-project config options may go in the global config (
/etc/stack/config.yaml) or the user config (
See Docker integration.
See Nix integration.
Integer indicating how many simultaneous downloads are allowed to happen
Strip out the "Loading ..." lines from GHC build output, produced when using Template Haskell
URL providing a JSON with information on the latest LTS and Nightly snapshots, used for automatic project configuration.
Target directory for
stack install and
stack build --copy-bins.
package-indices: - name: Hackage download-prefix: https://s3.amazonaws.com/hackage.fpcomplete.com/package/ # HTTP location of the package index http: https://s3.amazonaws.com/hackage.fpcomplete.com/00-index.tar.gz # Or, if using Hackage Security below, give the root URL: http: https://s3.amazonaws.com/hackage.fpcomplete.com/ # optional fields, both default to false require-hashes: false # Starting with stack 1.4, we default to using Hackage Security hackage-security: keyids: ["deadbeef", "12345"] # list of all approved keys key-threshold: 3 # number of keys required
One thing you should be aware of: if you change the contents of package-version combination by setting a different package index, this can have an effect on other projects by installing into your shared snapshot database.
Note that older versions of Stack supported Git-based indices. This feature has since been removed. A line such as:
git: https://github.com/commercialhaskell/all-cabal-hashes.git gpg-verify: false
Will now be ignored.
Enables or disables using the GHC available on the PATH.
Useful to enable if you want to save the time, bandwidth or storage space needed to setup an isolated GHC.
false unless the Docker or Nix integration is enabled.
In a Nix-enabled configuration, stack is incompatible with
# Turn on system GHC system-ghc: true
Whether or not to automatically install GHC when necessary. Default is
which means stack will prompt you to run
stack setup as needed.
Should we skip the check to confirm that your system GHC version (on the PATH)
matches what your project expects? Default is
Require a version of stack within the specified range
to be used for this project. Example:
require-stack-version: "== 0.1.*"
Set the architecture and operating system for GHC, build directories, etc. Values are those recognized by Cabal, e.g.:
arch: i386, x86_64 os: windows, linux
You likely only ever want to change the arch value. This can also be set via the command line.
A list of extra paths to be searched for header files and libraries, respectively. Paths should be absolute
extra-include-dirs: - /opt/foo/include extra-lib-dirs: - /opt/foo/lib
Specify a path to gcc explicitly, rather than relying on the normal path resolution.
Specifies how the compiler version in the resolver is matched against concrete versions. Valid values:
match-minor: make sure that the first three components match, but allow patch-level differences. For example< 18.104.22.168 and 22.214.171.124 would both match 7.8.4. This is useful to allow for custom patch levels of a compiler. This is the default
match-exact: the entire version number must match precisely
newer-minor: the third component can be increased, e.g. if your resolver is
ghc-7.10.1, then 7.10.2 will also be allowed. This was the default up through stack 0.1.3
Overrides the compiler version in the resolver. Note that the
flag also applies to the version numbers. This uses the same syntax as compiler
ghcjs-0.1.0.20150924_ghc-7.10.2 (version used
for the 'old-base' version of GHCJS). While it's useful to override the
compiler for a variety of reasons, the main usecase is to use GHCJS with a
stackage snapshot, like this:
resolver: lts-3.10 compiler: ghcjs-0.1.0.20150924_ghc-7.10.2 compiler-check: match-exact
Allows specifying per-package and global GHC options:
ghc-options: # All packages "*": -Wall some-package: -DSOME_CPP_FLAG
Caveat emptor: setting options like this will affect your snapshot packages,
which can lead to unpredictable behavior versus official Stackage snapshots.
This is in contrast to the
ghc-options command line flag, which will only
affect the packages specified by the
Which packages do ghc-options on the command line get applied to? Before 0.1.6, the default value was
apply-ghc-options: locals # all local packages, the default # apply-ghc-options: targets # all local packages that are targets # apply-ghc-options: everything # applied even to snapshot and extra-deps
everything is a slightly dangerous value, as it can break invariants about your snapshot database.
Should we rebuild a package when its GHC options change? Before 0.1.6, this was a non-configurable true. However, in most cases, the flag is used to affect optimization levels and warning behavior, for which GHC itself doesn't actually recompile the modules anyway. Therefore, the new behavior is to not recompile on an options change, but this behavior can be changed back with the following:
Specify a variant binary distribution of GHC to use. Known values:
standard: This is the default, uses the standard GHC binary distribution
integersimple: Use a GHC bindist that uses integer-simple instead of GMP
- any other value: Use a custom GHC bindist. You should specify
stack setupknows where to download it, or pass the
stack setup --ghc-bindistargument on the command-line
This option is incompatible with
Specify a specialized architecture bindist to use. Normally this is
determined automatically, but you can override the autodetected value here.
Possible arguments include
Allows overriding from where tools like GHC and msys2 (on Windows) are downloaded. Most useful for specifying locations of custom GHC binary distributions (for use with the ghc-variant option):
setup-info: ghc: windows32-custom-foo: 7.10.2: url: "https://example.com/ghc-7.10.2-i386-unknown-mingw32-foo.tar.xz"
Or without using
url may be either URL or (since 1.2.0) absolute file path.
When using the
upload commands, this setting determines whether
the cabal file's dependencies should be modified to reflect PVP lower and upper
bounds. Values are
upper (add upper bounds),
lower bounds), and both (and upper and lower bounds). The algorithm it follows
- If an upper or lower bound already exists on a dependency, it's left alone
- When adding a lower bound, we look at the current version specified by
stack.yaml, and set it as the lower bound (e.g.,
foo >= 1.2.3)
- When adding an upper bound, we require less than the next major version
foo < 1.3)
For more information, see the announcement blog post.
NOTE Since Stack 1.5.0, each of the values listed above supports
-revision to the end of each value, e.g.
both-revision. This means that, when uploading to Hackage, Stack will
first upload your tarball with an unmodified
.cabal file, and then
upload a cabal file revision with the PVP bounds added. This can be
useful—especially combined with the
Stackage no-revisions feature—as
a method to ensure PVP compliance without having to proactively fix
bounds issues for Stackage maintenance.
Modify the code page for UTF-8 output when running on Windows. Default behavior is to modify.
Decide whether a custom
Setup.hs script should be run with an explicit list of
dependencies, based on the dependencies of the package itself. It associates the
name of a local package with a boolean. When it's
is built with an explicit list of packages. When it's
false (default), the
Setup.hs script is built without access to the local DB, but can access any
package in the snapshot / global DB.
Note that in the future, this will be unnecessary, once Cabal provides full support for explicit Setup.hs dependencies.
explicit-setup-deps: "*": true # change the default entropy: false # override the new default for one package
NOTE: since 1.4.0, Stack has support for Cabal's
(introduced in Cabal 1.24). If a
custom-setup block is provided in a
file, it will override the setting of
explicit-setup-deps, and instead rely
on the stated dependencies.
Ignore version bounds in .cabal files. Default is false.
Note that this also ignores lower bounds. The name "allow-newer" is chosen to match the commonly used cabal option.
Allow users other than the owner of the stack root directory (typically
to use the stack installation. The default is
false. POSIX systems only.
The intention of this option is to prevent file permission problems, for example
as the result of a
stack command executed under
The option is automatically enabled when
stack is re-spawned in a Docker process.
Allows setting build options which are usually specified on the CLI. Here are the settings with their defaults:
build: library-profiling: false executable-profiling: false copy-bins: false prefetch: false keep-going: false # NOTE: global usage of haddock can cause build failures when documentation is # incorrectly formatted. This could also affect scripts which use stack. haddock: false haddock-arguments: haddock-args:  # Additional arguments passed to haddock, --haddock-arguments # haddock-args: # - "--css=/home/user/my-css" open-haddocks: false # --open haddock-deps: false # if unspecified, defaults to true if haddock is set haddock-internal: false # These are inadvisable to use in your global configuration, as they make the # stack build CLI behave quite differently. test: false test-arguments: rerun-tests: true # Rerun successful tests additional-args:  # --test-arguments # additional-args: # - "--fail-fast" coverage: false no-run-tests: false bench: false benchmark-opts: benchmark-arguments: "" # benchmark-arguments: "--csv bench.csv" no-run-benchmarks: false force-dirty: false reconfigure: false cabal-verbose: false split-objs: false
Control which log output from local non-dependency packages to print to the console. By default, Stack will only do this when building a single target package or if the log contains warnings, to avoid generating unnecessarily verbose output.
dump-logs: none # don't dump logs even if they contain warnings dump-logs: warning # default: dump logs that contain warnings dump-logs: all # dump all logs for local non-dependency packages
Templates used with
stack new have a number of parameters that affect the
generated code. These can be set for all new projects you create. The result of
them can be observed in the generated LICENSE and cabal files.
The 5 parameters are:
- author-email - sets the
maintainerproperty in cabal
- author-name - sets the
authorproperty in cabal and the name used in LICENSE
- category - sets the
categoryproperty in cabal. This is used in Hackage. For examples of categories see Packages by category. It makes sense for
categoryto be set on a per project basis because it is uncommon for all projects a user creates to belong to the same category. The category can be set per project by passing
-p "category:value"to the
- copyright - sets the
copyrightproperty in cabal. It is typically the name of the holder of the copyright on the package and the year(s) from which copyright is claimed. For example:
Copyright (c) 2006-2007 Joe Bloggs
- github-username - used to generate
source-repositoryin cabal. For instance
stack new my-project new-templatewould result:
homepage: http://github.com/myusername/my-project#readme source-repository head type: git location: https://github.com/myusername/my-project
These properties can be set in
config.yaml as follows:
templates: params: author-name: Your Name author-email: email@example.com category: Your Projects Category copyright: 'Copyright (c) 2017 Your Name' github-username: yourusername
stack new can automatically initialize source control repositories
in the directories it creates. Source control tools can be specified with the
scm-init option. At the moment, only
git is supported.
templates: scm-init: git
Controls whether, when using
stack upload, the user's Hackage
username and password are stored in a local file. Default: true.
Customize the URLs where
stack looks for snapshot build plans.
The default configuration is
urls: latest-snapshot: https://www.stackage.org/download/snapshots.json lts-build-plans: https://raw.githubusercontent.com/fpco/lts-haskell/master/ nightly-build-plans: https://raw.githubusercontent.com/fpco/stackage-nightly/master/
latest-snapshot-url field has been deprecated in favor of
and will be removed in a future version of
Specifies how many build tasks should be run in parallel. This can be overloaded
on the commandline via
-jN, for example
-j2. The default is to use the
number of processors reported by your CPU. One usage for this might be to avoid
running out of memory by setting it to 1, like this:
Specifies relative path of work directory (default is
.stack-work. This can
also be specified by env var or cli flag, in particular, the earlier items in
this list take precedence:
--work-dir DIRpassed on the commandline
Skips checking for and installing msys2 when stack is setting up the
environment. This is only useful on Windows machines, and usually doesn't make
sense in project configurations, just in
config.yaml. Defaults to
if this is used, it only really makes sense to use it like this:
This option specifies whether test-suites should be executed concurrently with
each-other. The default for this is true, since this is usually fine and it
often means that tests can complete earlier. However, if some test-suites
require exclusive access to some resource, or require a great deal of CPU or
memory resources, then it makes sense to set this to
false (the default is
This option specifies additional directories to prepend to the PATH environment
variable. These will be used when resolving the location of executables, and
will also be visible in the
PATH variable of processes run by stack.
For example, to prepend
/path-to-some-dep/bin to your PATh:
extra-path: - /path-to-some-dep/bin
One thing to note is that other paths added by stack - things like the project's bin dir and the compiler's bin dir - will take precedence over those specified here (the automatic paths get prepended).
This overrides the location of the programs directory, where tools like ghc and msys get installed.
On most systems, this defaults to a folder called
within the stack root directory. On windows, if the
variable exists, then it defaults to
follows windows conventions.
This option specifies which template to use with
stack new, when none is
specified. The default is called
new-template. The other templates are listed
in the stack-templates repo.