Skip to content


After your project is built, you can distribute it using the publish command.

The -p/--publisher option controls which publisher to use, with the default being index.

Artifact selection

By default, the dist directory located at the root of your project will be used:

$ hatch publish
dist/hatch_demo-1rc0-py3-none-any.whl ... success
dist/hatch_demo-1rc0.tar.gz ... success


You can instead pass specific paths as arguments:

hatch publish /path/to/artifacts foo-1.tar.gz

Only files ending with .whl or .tar.gz will be published.


You can select the repository with which to upload using the -r/--repo option or by setting the HATCH_INDEX_REPO environment variable.

Rather than specifying the full URL of a repository, you can use a named repository from a publish.index.repos table defined in Hatch's config file:

url = "..."

The following repository names are reserved by Hatch and cannot be overridden:

Name Repository

The main repository is used by default.


The first time you publish to a repository you need to authenticate using the -u/--user (environment variable HATCH_INDEX_USER) and -a/--auth (environment variable HATCH_INDEX_AUTH) options. You will be prompted if either option is not provided.

The user that most recently published to the chosen repository is cached, with their credentials saved to the system keyring, so that they will no longer need to provide authentication information.

For automated releasing to PyPI, it is recommended that you use per-project API tokens.


You can require a confirmation prompt or use of the -y/--yes flag by setting publishers' disable option to true in either Hatch's config file or project-specific configuration (which takes precedence):

disable = true
disable = true
disable = true