Release notes:

• The change in major version from 3.x to 4.1 marks the introduction of Stack's support for GHC's Backpack module system for cross-package use.

Changes since v3.11.1:

Major changes:

• Stack now supports GHC's Backpack module system for cross-package use. (Private Backpack, where signatures and implementations are in the same package, was already supported.) When a package uses signatures and mixins to depend on an abstract interface provided by another package, Stack automatically creates the extra instantiation build steps that Cabal requires. This includes support for explicit renaming, multiple instantiations of the same indefinite package, transitive signature chains, sub-library signatures, and indefinite package from Hackage or snapshots. See the Backpack topic for details.

Behavior changes:

• When Stack's Nix integration is enabled and a shell-file is not specified, Stack sets LANG=C.UTF-8 (rather than en_US.UTF-8, which may not be available if Stack has been built from source).
• With Nix integration, Stack uses nix-instantiate before nix-shell, enabling Stack to catch and report when the Nix expression cannot be evaluated by Nix. The nix-instantiate-options option is added, accordingly.
• Stack's build command now warns if --force-dirty is specified but no local packages will be built.

Other enhancements:

• Add option --query ITEM, which can be specified multiple times, to Stack's ls dependencies text command (the default ls dependencies command), to cause Stack to filter out from the results all packages other than those queried. Like the existing --filter ITEM option, an item is either a package name or $locals for all project packages.

Bug fixes:

• If snapshot locations are cyclic, Stack reports an error rather than going round in circles.

See https://haskellstack.org/ for installation and upgrade instructions.

Changes since v3.9.3:

Major changes:

• On 64-bit Windows, the default msys-environment configuration option is now CLANG64, rather than MINGW64 (which remains an option). The MSYS2 project deprecated the latter environment on 15 March 2026. The GHC project has used the former toolchain from GHC 9.4.1. No default is provided for 32-bit Windows, rather than MINGW32 (which remains an option). The MSYS2 project ceased to actively support it on 17 May 2020. 32-bit Windows is not supported by the GHC project from GHC 9.0.1.

Behavior changes:

• Stack's default Nix integration now includes the cacert Nix package, in order to support Stack's use of crypton-x509-system >= 1.6.8.
• Following a change to the Stackage project's server API, the default value of the urls key includes recent-snapshots: https://stackage.org/api/v1/snapshots.
• The --[no-]keep-ghc-rts flag of Stack's config env command is now enabled by default, consistent with Stack's exec command.
• On Windows, in the Stack environment, the MSYS2 usr/local/bin directory (if it exists) is now searched before the MSYS2 usr/bin directory, rather than after.

Other enhancements:

• Bump to Hpack 0.39.6.
• Experimental: Add flag --[no-]semaphore (default: disabled) to Stack's build command, to allow GHC to use a system semaphore to perform compilation in parallel when possible. Supported, by default, by GHC 9.10.1 or later. The option is considered experiemental because, on Linux only, musl and non-musl semaphores are incompatible.
• Add option --reach <packages> to Stack's dot and ls dependencies commands, to prune packages that cannot reach any of the specified packages in the dependency graph.
• Add option --test-suite-timeout-grace=SECONDS to Stack's build command to request termination of a timed-out test suite process and, after the specified grace period, force termination. Used together with the existing --test-suite-timeout=SECONDS option.
• In YAML configuration files, the recent-snapshots key is introduced (under the urls key), to specify the URL used by Stack's ls snapshots remote command.
• In YAML configuration files (stack.yaml and config.yaml), an !include <file path> directive is now supported. This allows common configuration to be shared across multiple files. For example, a project that maintains multiple project-level configuration files for testing against different snapshots can use !include to avoid duplicating shared settings.
• Stack's config set command raises an error if the target configuration file excludes the key being set and includes an !include directive.
• Stack's config set snapshot command now works with other snapshot values in addition to snapshot synonymns.
• Add Stack's config compiler-tools command to create (when applicable) the compiler tools directory for the specified compiler version (implies Stack's config build-files command).

Bug fixes:

• Stack's dot and ls dependencies commands no longer prune a package with dependencies only because all its direct dependencies are to be pruned.
• After March 2026, Hackage requires Stack's user agent to be set when applying digest authentication to a request. Stack's upload command now does that, re-establishing authentication by Hackage username and password.
• Stack 3.9.3 and earlier fail to construct a build plan if project package A depends on project package B and package B's executables (only) depend on package A and the name of A is before that of B, alphabetically. That bug is fixed.
• Stack's config set commands will recreate the global-project directory contents, if Stack needs to consult its project-level configuration file and there is no file.
• The output of Stack's path --bin-path command is now consistent with the Stack environment in Stack's exec command and includes the bin directory of Stack's local install root directory.
• Stack now builds packages that depend directly on packages with the same name as a sublibrary or foreign library of the package.
• On Windows, Stack's build command now accepts a build directory that is a long path.

Thanks to all our contributors for this release:

• Bryan Richter
• Ching Pei Yang
• Dan Burton
• David Vollbracht
• Mike Pilgrem
• Olivier Benz

Changes since v3.9.3:

Major changes:

• On 64-bit Windows, the default msys-environment configuration option is now CLANG64, rather than MINGW64 (which remains an option). The MSYS2 project deprecated the latter environment on 15 March 2026. The GHC project has used the former toolchain from GHC 9.4.1. No default is provided for 32-bit Windows, rather than MINGW32 (which remains an option). The MSYS2 project ceased to actively support it on 17 May 2020. 32-bit Windows is not supported by the GHC project from GHC 8.12.

Behavior changes:

• Stack's default Nix integration now includes the cacert Nix package, in order to support Stack's use of crypton-x509-system >= 1.6.8.
• Following a change to the Stackage project's server API, the default value of the urls key includes recent-snapshots: https://stackage.org/api/v1/snapshots.
• The --[no-]keep-ghc-rts flag of Stack's config env command is now enabled by default, consistent with Stack's exec command.
• On Windows, in the Stack environment, the MSYS2 usr/local/bin directory (if it exists) is now searched before the MSYS2 usr/bin directory, rather than after.

Other enhancements:

• Bump to Hpack 0.39.5.
• Experimental: Add flag --[no-]semaphore (default: disabled) to Stack's build command, to allow GHC to use a system semaphore to perform compilation in parallel when possible. Supported, by default, by GHC 9.10.1 or later. The option is considered experiemental because, on Linux only, musl and non-musl semaphores are incompatible.
• Add option --reach <packages> to Stack's dot and ls dependencies commands, to prune packages that cannot reach any of the specified packages in the dependency graph.
• Add option --test-suite-timeout-grace=SECONDS to Stack's build command to request termination of a timed-out test suite process and, after the specified grace period, force termination. Used together with the existing --test-suite-timeout=SECONDS option.
• In YAML configuration files, the recent-snapshots key is introduced (under the urls key), to specify the URL used by Stack's ls snapshots remote command.
• In YAML configuration files (stack.yaml and config.yaml), an !include <file path> directive is now supported. This allows common configuration to be shared across multiple files. For example, a project that maintains multiple project-level configuration files for testing against different snapshots can use !include to avoid duplicating shared settings.
• Stack's config set command raises an error if the target configuration file excludes the key being set and includes an !include directive.
• Stack's config set snapshot command now works with other snapshot values in addition to snapshot synonymns.
• Add Stack's config compiler-tools command to create (when applicable) the compiler tools directory for the specified compiler version (implies Stack's config build-files command).

Bug fixes:

• Stack's dot and ls dependencies commands no longer prune a package with dependencies only because all its direct dependencies are to be pruned.
• After March 2026, Hackage requires Stack's user agent to be set when applying digest authentication to a request. Stack's upload command now does that, re-establishing authentication by Hackage username and password.
• Stack 3.9.3 and earlier fail to construct a build plan if project package A depends on project package B and package B's executables (only) depend on package A and the name of A is before that of B, alphabetically. That bug is fixed.
• Stack's config set commands will recreate the global-project directory contents, if Stack needs to consult its project-level configuration file and there is no file.
• The output of Stack's path --bin-path command is now consistent with the Stack environment in Stack's exec command and includes the bin directory of Stack's local install root directory.
• Stack now builds packages that depend directly on packages with the same name as a sublibrary or foreign library of the package.

See https://haskellstack.org/ for installation and upgrade instructions.

Release notes:

• This release fixes a potential bug for users of Stack's Docker integration.

Changes since v3.9.1:

Other enhancements:

• The resolver synonym for snapshot, informally deprecated from Stack 3.1.1, is formally deprecated in online and in-app documentation.

Bug fixes:

• Stack's Docker integration supports Docker client versions 29.0.0 and greater.

Thanks to all our contributors for this release:

• Jens Petersen
• Mike Pilgrem
• Olivier Benz

See https://haskellstack.org/ for installation and upgrade instructions.

Changes since v3.7.1:

Behavior changes:

• Where applicable and Stack supports the GHC version, only the wired-in packages of the actual version of GHC used are treated as wired-in packages.
• Stack now recognises ghc-internal as a GHC wired-in package.
• The configuration option package-index has a new default value: the keyids key lists the keys of the Hackage root key holders applicable from 2025-07-24.
• Stack's dot command now treats --depth the same way as the ls dependencies command, so that the nodes of stack dot --external --depth 0 are the same as the packages listed by stack ls dependencies --depth 0.
• When building GHC from source, on Windows, the default Hadrian build target is reloc-binary-dist and the default path to the GHC built by Hadrian is _build/reloc-bindist.
• Stack's haddock command no longer requires a package to have a main library that exposes modules.
• On Windows, the path segment platform\hash\ghc version, under .stack-work\install and .stack-work\hoogle, is hashed only once, rather than twice.

Other enhancements:

• Bump to Hpack 0.39.1.
• Consider GHC 9.14 to be a tested compiler and remove warnings.
• Consider Cabal 3.16 to be a tested library and remove warnings.
• From GHC 9.12.1, base is not a GHC wired-in package. In configuration files, the notify-if-base-not-boot key is introduced, to allow the exisitng notification to be muted if unwanted when using such GHC versions.
• Add flag --[no-]omit-this (default: disabled) to Stack's clean command to omit directories currently in use from cleaning (when --full is not specified).
• Add option -w as synonym for --stack-yaml.
• stack new now allows codeberg: as a service for template downloads
• In YAML configuration files, the compiler-target and compiler-bindist-path keys are introduced to allow, when building GHC from source, the Hadrian build target and Hadrian path to the built GHC to be specified.

Bug fixes:

• --PROG-option=<argument> passes --PROG-option=<argument> (and not --PROG-option="<argument>") to Cabal (the library).
• The message S-7151 now presents as an error, with advice, and not as a bug.
• Stack's dot command now uses a box to identify all GHC wired-in packages, not just those with no dependencies (being only rts).
• Stack's dot command now gives all nodes with no dependencies in the graph the maximum rank, not just those nodes with no relevant dependencies at all (being only rts, when --external is specified).
• Improved error messages for S-4634 and S-8215.
• Improved in-app help for the --hpack-force flag.

Thanks to all our contributors for this release:

• Alexey Kotlyarov
• Dino Morelli
• Jens Petersen
• Lauren Yim
• Mike Pilgrem
• Olivier Benz
• Simon Hengel
• Wolfram Kahl

Changes since v3.7.1:

Behavior changes:

• Where applicable and Stack supports the GHC version, only the wired-in packages of the actual version of GHC used are treated as wired-in packages.
• Stack now recognises ghc-internal as a GHC wired-in package.
• The configuration option package-index has a new default value: the keyids key lists the keys of the Hackage root key holders applicable from 2025-07-24.
• Stack's dot command now treats --depth the same way as the ls dependencies command, so that the nodes of stack dot --external --depth 0 are the same as the packages listed by stack ls dependencies --depth 0.
• When building GHC from source, on Windows, the default Hadrian build target is reloc-binary-dist and the default path to the GHC built by Hadrian is _build/reloc-bindist.
• Stack's haddock command no longer requires a package to have a main library that exposes modules.

Other enhancements:

• Bump to Hpack 0.38.2.
• Consider GHC 9.14 to be a tested compiler and remove warnings.
• Consider Cabal 3.16 to be a tested library and remove warnings.
• From GHC 9.12.1, base is not a GHC wired-in package. In configuration files, the notify-if-base-not-boot key is introduced, to allow the exisitng notification to be muted if unwanted when using such GHC versions.
• Add flag --[no-]omit-this (default: disabled) to Stack's clean command to omit directories currently in use from cleaning (when --full is not specified).
• Add option -w as synonym for --stack-yaml.
• stack new now allows codeberg: as a service for template downloads.
• In YAML configuration files, the compiler-target and compiler-bindist-path keys are introduced to allow, when building GHC from source, the Hadrian build target and Hadrian path to the built GHC to be specified.

Bug fixes:

• --PROG-option=<argument> passes --PROG-option=<argument> (and not --PROG-option="<argument>") to Cabal (the library).
• The message S-7151 now presents as an error, with advice, and not as a bug.
• Stack's dot command now uses a box to identify all GHC wired-in packages, not just those with no dependencies (being only rts).
• Stack's dot command now gives all nodes with no dependencies in the graph the maximum rank, not just those nodes with no relevant dependencies at all (being only rts, when --external is specified).
• Improved error messages for S-4634 and S-8215.
• Improved in-app help for the --hpack-force flag.

See https://haskellstack.org/ for installation and upgrade instructions.

Changes since v3.5.1:

Other enhancements:

• Bump to Hpack 0.38.1.
• The --extra-dep option of Stack's script command now accepts a YAML value specifying any immutable extra-dep. Previously only an extra-dep in the package index that could be specified by a YAML string (for example, acme-missiles-0.3@rev:0) was accepted.

Bug fixes:

• stack script --package <pkg-name> now uses GHC's -package-id option to expose the installed package, rather than GHC's -package option. For packages with public sub-libraries, -package <pkg> can expose an installed package other than one listed by ghc-pkg list <pkg>.
• Work around ghc-pkg bug where, on Windows only, it cannot register a package into a package database that is also listed in the GHC_PACKAGE_PATH environment variable. In previous versions of Stack, this affected stack script when copying a pre-compiled package from another package database.
• On Windows, when decompressing, and extracting, tools from archive files, Stack uses the system temporary directory, rather than the root of the destination drive, if the former is on the destination drive.

Thanks to all our contributors for this release:

• Max Ulidtko
• Mike Pilgrem
• Olivier Benz
• Simon Hengel

Changes since v3.5.1:

Other enhancements:

• Bump to Hpack 0.38.1.
• The --extra-dep option of Stack's script command now accepts a YAML value specifying any immutable extra-dep. Previously only an extra-dep in the package index that could be specified by a YAML string (for example, acme-missiles-0.3@rev:0) was accepted.

Bug fixes:

• stack script --package <pkg-name> now uses GHC's -package-id option to expose the installed package, rather than GHC's -package option. For packages with public sub-libraries, -package <pkg> can expose an installed package other than one listed by ghc-pkg list <pkg>.
• Work around ghc-pkg bug where, on Windows only, it cannot register a package into a package database that is also listed in the GHC_PACKAGE_PATH environment variable. In previous versions of Stack, this affected stack script when copying a pre-compiled package from another package database.
• On Windows, when decompressing, and extracting tools, from archive files, Stack uses the system temporary directory, rather than the root of the destination drive, if the former is on the destination drive.

See https://haskellstack.org/ for installation and upgrade instructions.

Changes since v3.3.1:

Behavior changes:

• Stack will also warn (message S-8432) if there is any non-ISO/IEC 8859-1 (Latin-1) character in Stack's 'programs' path, as hsc2hs does not work if there is such a character in the path to its default template template-hsc.h.
• Stack customizes setup using Cabal, so if a setup-depends field does not mention it as a dependency, Stack warns and adds the GHC boot package as a dependency. Previously, Stack would not do so but only warn that build errors were likely.

Other enhancements:

• Bump to Hpack 0.38.0.
• In YAML configuration files, the install-msys key is introduced, to enable or disable the download and installation of Stack-supplied MSYS2 when necessary (subject to skip-msys: false). The default is the same as the install-ghc setting (including if that is set at the command line). Consequently, the default behaviour of Stack is unaffected.
• Add the stack config set install-msys command to configure the install-msys option in YAML configuration files.
• Option allow-newer-deps is no longer classified as experimental in documentation.
• stack sdist and stack upload report the version of Cabal (the library) being used to check packages.
• Add the stack config build-files command to generate (when applicable) a Cabal file from a package description in the Hpack format and/or a lock file for Stack's project-level configuration, without taking any other build steps.

Thanks to all our contributors for this release:

• Mike Pilgrem
• Olivier Benz

Changes since v3.3.1:

Behavior changes:

• Stack will also warn (message S-8432) if there is any non-ISO/IEC 8859-1 (Latin-1) character in Stack's 'programs' path, as hsc2hs does not work if there is such a character in the path to its default template template-hsc.h.
• Stack customizes setup using Cabal, so if a setup-depends field does not mention it as a dependency, Stack warns and adds the GHC boot package as a dependency. Previously, Stack would not do so but only warn that build errors were likely.

Other enhancements:

• Bump to Hpack 0.38.0.
• In YAML configuration files, the install-msys key is introduced, to enable or disable the download and installation of Stack-supplied MSYS2 when necessary (subject to skip-msys: false). The default is the same as the install-ghc setting (including if that is set at the command line). Consequently, the default behaviour of Stack is unaffected.
• Add the stack config set install-msys command to configure the install-msys option in YAML configuration files.
• Option allow-newer-deps is no longer classified as experimental in documentation.
• stack sdist and stack upload report the version of Cabal (the library) being used to check packages.