## File: README.md

# Hatch



-----

Hatch is a modern, extensible Python project manager.

## Features

- Standardized [build system](https://hatch.pypa.io/latest/config/build/#build-system) with reproducible builds by default
- Robust [environment management](https://hatch.pypa.io/latest/environment/) with support for custom scripts and UV
- Configurable [Python distribution management](https://hatch.pypa.io/latest/tutorials/python/manage/)
- [Test execution](https://hatch.pypa.io/latest/tutorials/testing/overview/) with known best practices
- [Static analysis](https://hatch.pypa.io/latest/config/static-analysis/) with sane defaults
- Built-in Python [script runner](https://hatch.pypa.io/latest/how-to/run/python-scripts/)
- Easy [publishing](https://hatch.pypa.io/latest/publish/) to PyPI or other indices
- [Version](https://hatch.pypa.io/latest/version/) management
- Best practice [project generation](https://hatch.pypa.io/latest/config/project-templates/)
- Responsive [CLI](https://hatch.pypa.io/latest/cli/about/), ~2-3x [faster](https://github.com/pypa/hatch/actions/workflows/cli.yml) than equivalent tools

See the [Why Hatch?](https://hatch.pypa.io/latest/why/) page for more information.

## Documentation

The [documentation](https://hatch.pypa.io/) is made with [Material for MkDocs](https://github.com/squidfunk/mkdocs-material) and is hosted by [GitHub Pages](https://docs.github.com/en/pages).

## License

Hatch is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

---

## File: docs/index.md

# Hatch



{ role="img" }

| | |
| --- | --- |
| CI/CD | [{ loading=lazy .off-glb }](https://github.com/pypa/hatch/actions/workflows/test.yml) [{ loading=lazy .off-glb }](https://github.com/pypa/hatch/actions/workflows/build-hatch.yml) [{ loading=lazy .off-glb }](https://github.com/pypa/hatch/actions/workflows/build-hatchling.yml) |
| Docs | [{ loading=lazy .off-glb }](https://github.com/pypa/hatch/actions/workflows/docs-release.yml) [{ loading=lazy .off-glb }](https://github.com/pypa/hatch/actions/workflows/docs-dev.yml) |
| Package | [{ loading=lazy .off-glb }](https://pypi.org/project/hatch/) [{ loading=lazy .off-glb }](https://pypi.org/project/hatch/) [{ loading=lazy .off-glb }](https://pypi.org/project/hatch/) [{ loading=lazy .off-glb }](https://github.com/pypa/hatch/releases) |
| Meta | [{ loading=lazy .off-glb }](https://github.com/pypa/hatch) [{ loading=lazy .off-glb }](https://github.com/astral-sh/ruff) [{ loading=lazy .off-glb }](https://github.com/python/mypy) [{ loading=lazy .off-glb }](https://spdx.org/licenses/) [{ loading=lazy .off-glb }](https://github.com/sponsors/ofek) |



-----

Hatch is a modern, extensible Python project manager. See the [Why Hatch?](why.md) page for more information.



-   :material-hammer-wrench:{ .lg .middle } __Build system__

    ---

    Reproducible builds by default with a rich ecosystem of plugins

    [:octicons-arrow-right-24: Configure builds](config/build.md#build-system)

-   :material-lock:{ .lg .middle } __Environments__

    ---

    Robust environment management with support for custom scripts and UV

    [:octicons-arrow-right-24: Getting started](environment.md)

-   :material-language-python:{ .lg .middle } __Python management__

    ---

    Choose between easy manual installations or automatic as part of environments

    [:octicons-arrow-right-24: Try it](tutorials/python/manage.md)

-   :octicons-shield-check-24:{ .lg .middle } __Testing__

    ---

    Test execution with known best practices

    [:octicons-arrow-right-24: Run](tutorials/testing/overview.md)

-   :material-magnify-scan:{ .lg .middle } __Static analysis__

    ---

    Static analysis backed by Ruff with up-to-date, sane defaults

    [:octicons-arrow-right-24: Learn](config/internal/static-analysis.md)

-   :material-console-line:{ .lg .middle } __Script runner__

    ---

    Execute Python scripts with specific dependencies and Python versions

    [:octicons-arrow-right-24: Execute](how-to/run/python-scripts.md)

-   :material-publish:{ .lg .middle } __Publishing__

    ---

    Easily upload to PyPI or other indices

    [:octicons-arrow-right-24: See how](publish.md)

-   :octicons-number-24:{ .lg .middle } __Versioning__

    ---

    Streamlined workflow for bumping versions

    [:octicons-arrow-right-24: Managing versions](version.md)

-   :octicons-project-template-24:{ .lg .middle } __Project generation__

    ---

    Create new projects from templates with known best practices

    [:octicons-arrow-right-24: Project setup](intro.md#setup)

-   :material-speedometer:{ .lg .middle } __Responsive CLI__

    ---

    Hatch is up to 3x faster than equivalent tools

    [:octicons-arrow-right-24: CLI reference](cli/about.md)



## License

Hatch is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

## Navigation

Documentation for specific `MAJOR.MINOR` versions can be chosen by using the dropdown on the top of every page. The `dev` version reflects changes that have not yet been released.

Also, desktop readers can use special keyboard shortcuts:

| Keys | Action |
| --- | --- |
| <li><kbd>,</kbd> (comma)</li><li><kbd>p</kbd></li> | Navigate to the "previous" page |
| <li><kbd>.</kbd> (period)</li><li><kbd>n</kbd></li> | Navigate to the "next" page |
| <li><kbd>/</kbd></li><li><kbd>s</kbd></li> | Display the search modal |

---

## File: docs/intro.md

# Introduction

-----

## Setup

Projects can be set up for use by Hatch using the [`new`](cli/reference.md#hatch-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](config/project-templates.md) 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](config/metadata.md) located in the `pyproject.toml` file. You can specify things like its [license](config/metadata.md#license), the [supported versions of Python](config/metadata.md#python-support), and [URLs](config/metadata.md#urls) referring to various parts of your project, like documentation.

## Dependencies

The last step of the setup process is to define any [dependencies](config/dependency.md) 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:

```toml config-example
[tool.hatch]
option = "..."

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

[tool.hatch.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](https://toml.io/en/v1.0.0#table), turning the above example into:

    ```toml config-example
    [tool.hatch]
    option = "..."
    table1.option = "..."
    table2.option = "..."
    ```