Configure a Hatch environment

Hatch is a project management and packaging tool for Python.

Hatch can automatically migrate setuptools configurations, create isolated environments, and run and publish builds, making Python package management more efficient.

Hatch support in PyCharm

When you select Hatch while creating a new Python project, PyCharm automatically generates a pyproject.toml file. This file specifies required packages, scripts, plugins, and URLs. See the pyproject guide to learn more about its structure and format.

The newly created project would have the following structure:

                project_name
                ├── src
                │   └── project_name
                │       ├── __about__.py
                │       └── __init__.py
                ├── tests
                │   └── __init__.py
                ├── LICENSE.txt
                ├── pyproject.toml
                └── README.md
            

If you want to work with your existing projects, PyCharm will also automatically recognize Hatch projects when they are imported from a local machine or a remote source.

To use Hatch in PyCharm, you need to create a specific Python environment.

Create a Hatch environment

Do one of the following:
- Click the Python Interpreter selector and choose Add New Interpreter.
- Press Ctrl+Alt+S to open Settings and go to Project: <project name> | Python Interpreter. Click the Add Interpreter link next to the list of the available interpreters.
- Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.
Select Add Local Interpreter.
The following actions depend on whether you want to generate a new virtual environment or to use an existing one.
New Hatch environment
1. Select Hatch from the list of environment types.
2. Select an environment.
  Hatch environments are workspaces designed for various project-specific tasks. If no environment is explicitly selected, Hatch will use the default environment.
3. Select the base interpreter from the list, or click and find the Python executable in your file system.
4. Normally, PyCharm will detect Hatch installation.
  Otherwise, specify the location of the Hatch executable, or click to browse for it.
Existing Hatch environment
1. Select Hatch from the list of environment types.
2. Select the environment from the list.
3. Normally, PyCharm will detect Hatch installation.
  Otherwise, specify the location of the Hatch executable, or click to browse for it.
Click OK to complete the task.

For any of the configured Python interpreters (but Docker-based), you can:

Last modified: 15 April 2025