Introduction¶

Setup¶

Projects can be set up for use by Hatch using the new command.

New project¶

Let's say you want to create a project named Hatch Demo. You would run:


hatch new "Hatch Demo"

This would create the following structure in your current working directory:


hatch-demo
├── src
│   └── hatch_demo
│       ├── __about__.py
│       └── __init__.py
├── tests
│   └── __init__.py
├── LICENSE.txt
├── README.md
└── pyproject.toml

Tip

There are many ways to customize project generation.

Existing project¶

To initialize an existing project, enter the directory containing the project and run the following:


hatch new --init

If your project has a setup.py file the command will automatically migrate setuptools configuration for you. Otherwise, this will interactively guide you through the setup process.

Project metadata¶

Next you'll want to define more of your project's metadata located in the pyproject.toml file. You can specify things like its license, the supported versions of Python, and URLs referring to various parts of your project, like documentation.

Dependencies¶

The last step of the setup process is to define any dependencies that you'd like your project to begin with.

Configuration¶

All project-specific configuration recognized by Hatch can be defined in either the pyproject.toml file, or a file named hatch.toml where options are not contained within the tool.hatch table:

pyproject.toml hatch.toml


[tool.hatch]
option = "..."

[tool.hatch.table1]
option = "..."

[tool.hatch.table2]
option = "..."


option = "..."

[table1]
option = "..."

[table2]
option = "..."

Top level keys in the latter file take precedence when defined in both.

Tip

If you want to make your file more compact, you can use dotted keys, turning the above example into:

pyproject.toml hatch.toml


[tool.hatch]
option = "..."
table1.option = "..."
table2.option = "..."


option = "..."
table1.option = "..."
table2.option = "..."