{"id":1169,"library":"hatch","title":"Hatch Project Management","description":"Hatch is a modern, extensible Python project manager that centralizes environment management, packaging with Hatchling, versioning, and publishing behind a single command-line interface. It is known for its ability to seamlessly manage multiple environments, handle dependencies, and dynamically download required Python distributions. Currently at version 1.16.5, Hatch maintains an active development and release cadence.","status":"active","version":"1.16.5","language":"python","source_language":"en","source_url":"https://github.com/pypa/hatch","tags":["project management","build system","packaging","virtual environments","dependency management"],"install":[{"cmd":"pip install hatch","lang":"bash","label":"Standard installation"},{"cmd":"pipx install hatch","lang":"bash","label":"Recommended for CLI tools"}],"dependencies":[{"reason":"Hatch's standardized build backend.","package":"hatchling","optional":false},{"reason":"Added in v1.16.5 to handle breaking changes in `virtualenv`.","package":"python-discovery","optional":false},{"reason":"CLI toolkit dependency.","package":"click","optional":false},{"reason":"Used for rich terminal output.","package":"rich","optional":false}],"imports":[],"quickstart":{"code":"# Create a new Python project\nhatch new \"My Awesome Project\"\n\n# Navigate into the project directory\ncd \"my-awesome-project\"\n\n# Run a script (e.g., 'python -m my_awesome_project')\n# This assumes a default `run` script is defined in pyproject.toml\nhatch run python -c \"print('Hello from Hatch!')\"\n\n# Or enter a shell environment\n# hatch shell","lang":"bash","description":"Hatch is primarily a CLI tool. This quickstart demonstrates creating a new project and running a simple command within its managed environment. The `hatch new` command scaffolds a new project with a `pyproject.toml` file, and `hatch run` executes commands within the project's isolated environment."},"warnings":[{"fix":"Upgrade your project's Python version to 3.10 or newer, or pin Hatch to a version <1.16.0 (e.g., `hatch<1.16.0`).","message":"Hatch v1.16.0 dropped official support for Python 3.9. Projects requiring Python 3.9 or older must use an earlier version of Hatch.","severity":"breaking","affected_versions":">=1.16.0"},{"fix":"Upgrade your project's Python version to 3.9 or newer, or pin Hatch to a version <1.15.0 (e.g., `hatch<1.15.0`).","message":"Hatch v1.15.0 dropped official support for Python 3.8. Projects requiring Python 3.8 or older must use an earlier version of Hatch.","severity":"breaking","affected_versions":">=1.15.0"},{"fix":"Refer to the Hatch v1.16.0 release notes and documentation for updated environment plugin API. All environments can now be used for building.","message":"In Hatch v1.16.0, several environment type plugin methods were removed (`build_environment`, `build_environment_exists`, `run_builder`, `construct_build_command`). Custom environment plugins might need updates.","severity":"breaking","affected_versions":">=1.16.0"},{"fix":"Upgrade Hatch to v1.16.5 or newer to ensure compatibility with `virtualenv`.","message":"Hatch v1.16.5 fixed a breaking change in `virtualenv` by explicitly supporting only the latest version and adding `python-discovery` as a dependency. Older Hatch versions might encounter issues with newer `virtualenv`.","severity":"gotcha","affected_versions":"<1.16.5"},{"fix":"Upgrade Hatch to v1.16.3 or newer to resolve issues with dependency recognition and environment creation stability.","message":"Prior to v1.16.3, there were known issues with self-referential dependencies not being recognized and incomplete environments being created when exceptions occurred during environment setup.","severity":"gotcha","affected_versions":"<1.16.3"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z","problems":[{"fix":"Ensure Hatch is installed globally using `pipx install hatch` (recommended) or one of the official standalone installers for your operating system. After installation, restart your terminal to refresh the PATH.","cause":"The 'hatch' executable is not located in your system's PATH environment variable, or Hatch was not installed correctly.","error":"hatch: command not found"},{"fix":"Ensure your `pyproject.toml` correctly specifies the package location. If using a `src` layout, add or verify the `packages` entry under `[tool.hatch.build.targets.wheel]` (or other relevant build target) to point to your source directory, e.g., `packages = [\"src/your_package_name\"]`.","cause":"When using a `src` directory layout, the Python interpreter within the Hatch environment may not correctly locate your project's main package, often due to missing or incorrect `packages` configuration in `pyproject.toml`.","error":"ModuleNotFoundError: No module named 'your_package_name'"},{"fix":"Try closing any IDEs (like VS Code) that might be locking project files. Ensure all necessary build hook dependencies are declared in `build-system.requires` or within the specific hook's configuration in `pyproject.toml`. If the issue persists, try deleting the `.hatch` directory (usually in your user's local application data) to force a clean environment recreation.","cause":"A subprocess involved in building editable metadata or installing build dependencies failed. This can be due to file locking by an IDE, missing build hook dependencies, or environmental issues, particularly on Windows.","error":"error: subprocess-exited-with-error × Preparing editable metadata (pyproject.toml) did not run successfully."},{"fix":"As a workaround, you can try disabling certain Hatch environment plugins (e.g., `hatch-pip-compile`) by commenting them out in your `pyproject.toml` (e.g., `#[tool.hatch.envs.default.plugins.pip-compile]`), then prune and recreate the environment using `hatch env prune` and `hatch env create`. Additionally, ensure both PyCharm and its Hatch plugin are updated to their latest versions.","cause":"This error occurs in PyCharm when its Hatch plugin or specific Hatch environment plugins interfere with PyCharm's ability to discover and list available Hatch environments.","error":"Hatch didn't provide any environment to select."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}