Skip to content

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 the standard.

Name (required)

The name of the project.

[project]
name = "your-app"

Version (required)

See the dedicated versioning section.

[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.

The file extension must be .md, .rst, or .txt.

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

The content-type field must be set to text/markdown, text/x-rst, or text/plain.

A charset field may also be set to instruct which encoding to use for reading the file, defaulting to utf-8.

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

The content-type field must be set to text/markdown or text/x-rst.

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

Note

If this is defined as a file, then it will always be included in source distributions for consistent builds.

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

See the dependency specification page 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

Deprecated

This option temporarily exists to provide better interoperability with tools that do not yet support PEP 685 and will be removed in the first minor release after Jan 1, 2024.