Stack's global flags and options¶
Stack can also be configured by flags and options on the command line. Global
flags and options apply to all of Stack's commands. In addition, all of Stack's
commands accept the --setup-info-yaml and --snapshot-location-base options
and the --help flag.
--allow-different-user flag¶
Restrictions: POSIX systems only
Default: True, if inside Docker; false otherwise
Enable/disable permitting users other than the owner of the Stack root directory to use a Stack installation. For further information, see the documentation for the corresponding non-project specific configuration option.
--arch option¶
Pass the option --arch <architecture> to specify the relevant machine
architecture. For further information, see the documentation for the
corresponding non-project specific configuration
option.
--bash-completion-index option¶
Visibility: Hidden
See the shell auto-completion documentation.
--bash-completion-script option¶
Visibility: Hidden
See the shell auto-completion documentation.
--bash-completion-index option¶
Visibility: Hidden
See the shell auto-completion documentation.
--color or -colour options¶
Pass the option stack --color <when> to specify when to use color in output.
For further information, see the documentation for the corresponding non-project
specific configuration option.
--compiler option¶
Pass the option --compiler <compiler> to specify the compiler (and,
implicitly, its boot packages). For further information, see the
compiler non-project specific configuration
option documentation.
--custom-preprocessor-extensions option¶
Pass the option --custom-preprocessor-extensions <extension> to specify an
extension used for a custom preprocessor. For further information, see the
documentation for the corresponding project specific configuration
option.
--docker* flags and options¶
Stack supports automatically performing builds inside a Docker container. For
further information see stack --docker-help or the
Docker integration documentation.
--[no-]dump-logs flag¶
Default: Dump warning logs
Enables/disables the dumping of the build output logs for project packages to the console. For further information, see the documentation for the corresponding non-project specific configuration option.
--extra-include-dirs option¶
Pass the option --extra-include-dirs <director> to specify an extra directory
to check for C header files. The option can be specified multiple times. For
further information, see the documentation for the corresponding non-project
specific configuration option.
--extra-lib-dirs option¶
Pass the option --extra-lib-dirs <director> to specify an extra directory
to check for libraries. The option can be specified multiple times. For further
information, see the documentation for the corresponding non-project specific
configuration option.
--fish-completion-script option¶
Visibility: Hidden
See the shell auto-completion documentation.
--ghc-build option¶
Pass the option --ghc-build <build> to specify the relevant specialised GHC
build. For further information, see the documentation for the corresponding
non-project specific configuration option.
--ghc-variant option¶
Pass the option --ghc-variant <variant> to specify the relevant GHC variant.
For further information, see the documentation for the corresponding non-project
specific configuration option.
--help or -h flags¶
Pass the --help (or -h) flag to cause Stack to list its commands and flags
and options common to those commands. Alternatively, command
for the same information.
--[no-]hpack-force flag¶
Default: Disabled
By default, Hpack 0.12.0 or later will decline to overwrite a Cabal file that
was created by a more recent version of Hpack and Hpack 0.20.0 or later will
decline to overwrite a Cabal file that has been modified manually. Pass the flag
--hpack-force to allow Hpack to overwrite such a Cabal file.
--hpack-numeric-version flag¶
Pass the flag --hpack-numeric-version to cause Stack to report the numeric
version of its built-in Hpack library to the standard output stream (e.g.
0.35.0) and quit.
--[no-]install-ghc flag¶
Default: Enabled ( 1.6.1)
If the specified GHC version is not available, enables/disables Stack seeking to
download and install that version if it is needed. On Windows,
--no-install-ghc also disables the download and installation of the
Stack-supplied MSYS2 when it is needed. For further information, see the
documentation for the corresponding non-project specific configuration
option.
Note
The --[no-]install-ghc flag does not specify whether Stack checks the
availability of either a 'system' GHC executable on the PATH or a
Stack-supplied GHC executable. In that regard, see the
system-ghc option.
--[no-]install-msys flag¶
Restrictions: Windows systems only
Default: Same as the install-ghc setting
(including if that is set on the command line)
If Stack is checking for the Stack-supplied MSYS2 when Stack is setting up the environment, enables/disables the download and installation of MSYS2 when necessary. For further information, see the documentation for the corresponding non-project specific configuration option.
To skip entirely checking for the Stack-supplied MSYS2, see the documentation
for the skip-msys configuration option.
--jobs or -j option¶
Pass the option --jobs <number_of_jobs> to specify the number of concurrent
jobs (Stack actions during building) to run.
When building GHC from source, specifies the
-j[<n>] flag of GHC's Hadrian build system.
By default, Stack specifies a number of concurrent jobs equal to the number of
CPUs (cores) that the machine has. In some circumstances, that default can cause
some machines to run out of memory during building. If those circumstances
arise, specify --jobs 1.
This configuration option is distinct from GHC's own -j[<n>] flag, which
relates to parallel compilation of modules within a package.
For further information, see the documentation for the corresponding non-project
specific configuration option: jobs.
--local-bin-path option¶
Pass the option --local-bin-path <directory> to set the target directory for
stack build --copy-bins and
stack install. An absolute or relative path can be specified. A relative path
at the command line is always assumed to be relative to the current directory.
For further information, see the documentation for the corresponding non-project specific configuration option.
--lock-file option¶
Default: read-write, if snapshot specified in the project-level configuration
file; read-only, if a different snapshot is specified on the command line.
Pass the option --lock-file <mode> to specify how Stack interacts with lock
files. Valid modes are:
error-on-write: Stack reports an error, rather than write a lock file;ignore: Stack ignores lock files;read-only: Stack only reads lock files; andread-write: Stack reads and writes lock files.
--[no-]modify-code-page flag¶
Restrictions: Windows systems only
Default: Enabled
Enables/disables setting the codepage to support UTF-8. For further information, see the documentation for the corresponding non-project specific configuration option.
--nix* flags and options¶
Stack can be configured to integrate with Nix. For further information, see
stack --nix-help or the Nix integration
documentation.
--numeric-version flag¶
Pass the flag --numeric-version to cause Stack to report its numeric version
to the standard output stream (e.g. 2.9.1) and quit.
--[no-]plan-in-log flag¶
Default: Disabled
Enables/disables the logging of build plan construction in debug output. Information about the build plan construction can be lengthy. If you do not need it, it is best omitted from the debug output.
--resolver option¶
The --resolver option (deprecated) and the --snapshot
option are synonyms.
More than one of these options is prohibited.
--[no-]rsl-in-log flag¶
Default: Disabled
Enables/disables the logging of the raw snapshot layer (rsl) in debug output. Information about the raw snapshot layer can be lengthy. If you do not need it, it is best omitted from the debug output.
--[no-]script-no-run-compile flag¶
Default: Disabled
Enables/disables the use of options --no-run --compile with the
stack script command.
--silent flag¶
Equivalent to the --verbosity silent option.
--[no-]skip-ghc-check option¶
Default: Disabled
Enables/disables the skipping of checking the GHC version and architecture. For further information, see the documentation for the corresponding non-project specific configuration option.
--[no-]skip-msys option¶
Restrictions: Windows systems only
Default: Disabled
Enables/disables the skipping of checking for the Stack-supplied MSYS2 (and installing that MSYS2, if it is not installed) when Stack is setting up the environment. For further information, see the documentation for the corresponding non-project specific configuration option.
To prevent installation of MSYS2, if it is not installed, see the documentation
for the install-msys configuration option.
--snapshot option¶
Pass the option --snapshot <snapshot> to specify the snapshot. For further
information, see the snapshot project-specific
configuration option documentation.
--stack-colors or --stack-colours options¶
Pass the option --stack-colors <styles> to specify Stack's output styles. For
further information, see the documentation for the corresponding non-project
specific configuration option.
--stack-root option¶
Overrides: STACK_ROOT environment variable
Pass the option --stack-root <absolute_path_to_the_Stack_root> to specify the
path to the Stack root directory. The path must be an
absolute one.
--stack-yaml or -w option¶
Default: stack.yaml
Overrides: STACK_YAML enviroment variable
Pass the option --stack-yaml <file> to specify Stack's project-level YAML
configuration file.
--[no-]system-ghc flag¶
Default: Disabled ( 1.3.0)
Enables/disables Stack seeking to use a 'system' GHC executable (that is, one on the PATH) rather than a Stack-supplied GHC executable (or vice versa, if disabled). For further information, see the documentation for the corresponding non-project specific configuration option.
Note
The --[no-]system-ghc flag does not specify Stack's behaviour if the
specified GHC version is not already available. In that regard, see the
install-ghc option.
--[no-]terminal flag¶
Default: Stack is running in a terminal (as detected)
Enables/disables whether Stack is running in a terminal.
--terminal-width option¶
Default: the terminal width (if detected); otherwise 100
Pass the option --terminal-width <width> to specify the width of the terminal,
used by Stack's pretty printed messages.
--[no-]time-in-logs flag¶
Default: Enabled
Enables/disables the inclusion of time stamps against logging entries when the verbosity level is 'debug'.
--verbose or -v flags¶
Equivalent to the --verbosity debug option.
--verbosity option¶
Default: info
Pass the option --verbosity <log_level> to specify the level for logging.
Possible levels are silent, error, warn, info and debug, in order of
increasing amounts of information provided by logging.
--version flag¶
Pass the flag --version to cause Stack to report its version to standard
output and quit. For versions that are release candidates, the report will list
the dependencies that Stack has been compiled with.
--with-gcc option¶
Pass the option --with-gcc <path_to_gcc> to specify use of a GCC executable.
For further information, see the documentation for the corresponding non-project
specific configuration option.
--with-hpack option¶
Pass the option --with-hpack <hpack> to specify use of an Hpack executable.
For further information, see the documentation for the corresponding
non-project specific configuration option.
--work-dir option¶
Default: .stack-work
Overrides: STACK_WORK environment
variable, and work-dir non-project specific
configuration option.
Pass the option --work-dir <relative_path_to_the_Stack_root> to specify the
path to Stack's work directory, within a local project or package directory. The
path must be a relative one, relative to the the root directory of the project
or package. The relative path cannot include a .. (parent directory)
component.
--zsh-completion-script option¶
Visibility: Hidden
See the shell auto-completion documentation.
--setup-info-yaml command option¶
Default: https://raw.githubusercontent.com/commercialhaskell/stackage-content/master/stack/stack-setup-2.yaml
The --setup-info-yaml <url> command option specifies the location of a
setup-info dictionary. The option can be specified multiple times.
--snapshot-location-base command option¶
Default: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master
The --snapshot-location-base <url> command option specifies the base location
of snapshots. For further information, see the documentation for the
corresponding non-project specific configuration
option.
--help or -h command flags¶
If Stack is passed the --help (or -h) command flag, it will output help for
the command.