Project metadata¶

Project metadata is stored in a pyproject.toml file located at the root of a project's tree and is based entirely on PEP 621.

Name (required)¶

The name of the project.

[project]
name = "your-app"

Version (required)¶

[project]
...
dynamic = ["version"]

[tool.hatch.version]
path = "..."

[project]
...
version = "0.0.1"

Description¶

A brief summary of the project.

[project]
...
description = '...'

Readme¶

The full description of the project.

[project]
...
readme = "README.md"

[project]
...
readme = {"file" = "README.md", "content-type" = "text/markdown"}

[project]
...
readme = {"text" = "...", "content-type" = "text/markdown"}

Python support¶

The Python version requirements of the project.

[project]
...
requires-python = ">=3.8"

License¶

For more information, see PEP 639.

[project]
...
license = "Apache-2.0 OR MIT"

[project]
...
license-files = { paths = ["LICENSE.txt"] }

[project]
...
license-files = { globs = ["LICENSES/*"] }

Ownership¶

The people or organizations considered to be the authors or maintainers of the project. The exact meaning is open to interpretation; it may list the original or primary authors, current maintainers, or owners of the package. If the values are the same, prefer only the use of the authors field.

[project]
...
authors = [
  { name = "...", email = "..." },
]
maintainers = [
  { name = "...", email = "..." },
]

Keywords¶

The keywords used to assist in the discovery of the project.

[project]
...
keywords = [
  "...",
]

Classifiers¶

The trove classifiers that apply to the project.

[project]
...
classifiers = [
  "...",
]

URLs¶

A table of URLs where the key is the URL label and the value is the URL itself.

[project.urls]
Documentation = "..."
"Source code" = "..."

Dependencies¶

The format is based on PEP 631. See the dependency specification section for more information.

Entries support context formatting and disallow direct references by default.

Required¶

[project]
...
dependencies = [
  "...",
]

Optional¶

[project.optional-dependencies]
option1 = [
  "...",
]
option2 = [
  "...",
]

Entry points¶

Entry points are a mechanism for the project to advertise components it provides to be discovered and used by other code.

CLI¶

After installing projects that define CLI scripts, each key will be available along your PATH as a command that will call its associated object.

[project.scripts]
cli-name = "pkg.subpkg:func"

Using the above example, running cli-name would essentially execute the following Python script:

import sys

from pkg.subpkg import func

sys.exit(func())

GUI¶

GUI scripts are exactly the same as CLI scripts except on Windows, where they are handled specially so that they can be started without a console.

[project.gui-scripts]
gui-name = "pkg.subpkg:func"

Plugins¶

[project.entry-points.plugin-namespace]
plugin-name1 = "pkg.subpkg1"
plugin-name2 = "pkg.subpkg2:func"

Dynamic¶

If any metadata fields are set dynamically, like the version may be, then they must be listed here.

[project]
...
dynamic = [
  "...",
]

Metadata options¶

Allowing direct references¶

By default, dependencies are not allowed to define direct references. To disable this check, set allow-direct-references to true:

[tool.hatch.metadata]
allow-direct-references = true

[metadata]
allow-direct-references = true

Allowing ambiguous features¶

By default, names of optional dependencies are normalized to prevent ambiguity. To disable this normalization, set allow-ambiguous-features to true:

[tool.hatch.metadata]
allow-ambiguous-features = true

[metadata]
allow-ambiguous-features = true