Skip to content

The stack upload command

stack upload [ITEM] [-d|--documentation] [--pvp-bounds PVP-BOUNDS]
             [--ignore-check] [--[no-]test-tarball] [--tar-dir ARG]
             [--candidate] [--[no-]save-hackage-creds] [--setup-info-yaml URL]
             [--snapshot-location-base URL]

By default:

  • the command uploads one or more packages. Pass the flag --documentation (-d for short) to upload documentation for one or more packages;

  • the upload is a package to be published or documentation for a published package. Pass the flag --candidate to upload a package candidate or documentation for a package candidate; and

  • the command prompts to save the user's Hackage username and password in a local file. Pass the flag --no-save-hackage-creds to avoid the prompt.

At least one ITEM must be specified. For example, if the current working directory is a package directory:

stack upload .

Upload one or more packages

Hackage accepts packages for uploading in a standard form, a compressed archive ('tarball') in the format produced by Cabal's sdist action.

If ITEM is a relative path to an sdist tarball, stack upload uploads the package to Hackage.

If ITEM is a relative path to a package directory, stack upload generates a file for your package, in the format accepted by Hackage for uploads, and uploads the package to Hackage.

By default:

  • the command will check each package for common mistakes. For further information, see the stack sdist command documentation. Pass the flag --ignore-check to disable such checks; and

  • Stack will not test the resulting package archive. Pass the flag --test-tarball to cause Stack to test each resulting package archive, by attempting to build it.

The --pvp-bounds <pvp_bounds_mode> option determines whether and, if so, how PVP version bounds should be added to the Cabal file of the package. The available modes for basic use are: none, lower, upper, and both. The available modes for use with Cabal file revisions are lower-revision, upper-revision and both-revision.

For futher information, see the pvp-bounds non-project specific configuration option documentation.

The --tar-dir <path_to_directory> option determines whether the package archive should be copied to the specified directory.

Upload documentation for a package

Experimental

2.15.1

Hackage accepts documentation for a package for uploading in a standard form and in a compressed archive ('tarball') in the .tar.gz format.

For further information about how to create such an archive file, see the documentation for the stack haddock --haddock-for-hackage command.

If ITEM is a relative path to a package directory, stack upload <package_directory> --documentation uploads an existing archive file of documentation for the specified package to Hackage.

If the --documentation flag is passed then flags specific to package upload are ignored.

The HACKAGE_USERNAME and HACKAGE_PASSWORD environment variables

2.3.1

Warning

After March 2026, Hackage requires Stack to add its user agent when applying digest authentication to a request. Stack 3.9.3 and earlier do not do this. Consequently, Stack's upload command is unable to submit digest credentials and encounters an authentication failure when uploading to the server. A work around is to use the HACKAGE_KEY environment variable.

stack upload will request a Hackage username and password to authenticate. This can be avoided by setting the HACKAGE_USERNAME and HACKAGE_PASSWORD environment variables. For example:

export $HACKAGE_USERNAME="<username>"
export $HACKAGE_PASSWORD="<password>"
stack upload .

$Env:HACKAGE_USERNAME='<username>'
$Env:HACKAGE_PASSWORD='<password>'
stack upload .

set HACKAGE_USERNAME=<username>
set HACKAGE_PASSWORD=<password>
stack upload .

The HACKAGE_KEY environment variable

2.7.5

Hackage allows its members to register an API authentification token and to authenticate using the token.

A Hackage API authentification token can be used with stack upload instead of username and password, by setting the HACKAGE_KEY environment variable. For example:

HACKAGE_KEY=<api_authentification_token>
stack upload .

$Env:HACKAGE_KEY=<api_authentification_token>
stack upload .

set HACKAGE_KEY=<api_authentification_token>
stack upload .