hatch

Modern Python project manager. pyproject.toml 기반 프로젝트 생성, environment 관리, build, publish 흐름을 한 도구로 묶는다.

• Hatch는 PyPA 계열 Python 프로젝트 관리 도구다.
• 프로젝트 템플릿 생성, environment 실행, package build, publish, version 관리 명령을 제공한다.
• 공식 문서 최신 경로는 2026-06-21 확인 시점 기준 https://hatch.pypa.io/1.17/ 이다.

hatch [OPTIONS] COMMAND [ARGS]...

• hatch [OPTIONS] COMMAND [ARGS]…
• hatch new NAME [LOCATION]
• hatch run [ENV:]ARGS…
• hatch shell [ENV_NAME]
• hatch build [LOCATION]
• hatch publish [ARGS]…

• -e, –env ENV_NAME: 기본 environment 선택. HATCH_ENV 사용 가능.
• -p, –project PROJECT: 작업할 project 지정. HATCH_PROJECT 사용 가능.
• -v, –verbose: verbosity 증가. 여러 번 사용 가능. HATCH_VERBOSE 사용 가능.
• -q, –quiet: verbosity 감소. 여러 번 사용 가능. HATCH_QUIET 사용 가능.
• –color, –no-color: colored output 제어.
• –interactive, –no-interactive: prompt/progress 허용 여부 제어. HATCH_INTERACTIVE 사용 가능.
• –data-dir PATH: persistent data 디렉터리 지정. HATCH_DATA_DIR 사용 가능.
• –cache-dir PATH: cache 디렉터리 지정. HATCH_CACHE_DIR 사용 가능.
• –config FILE: custom config file 지정. HATCH_CONFIG 사용 가능.

• new: 새 project 생성 또는 기존 project 초기화.
• run: project environment 안에서 명령 실행. env run wrapper.
• shell: project environment shell 진입.
• build: sdist / wheel artifact 생성.
• publish: PyPI 등 package index로 배포.
• version: project version 조회/변경.
• env: environment 관리.
• python: Python runtime 관리.
• test: test workflow 실행.
• fmt: formatting workflow 실행.
• clean: build/output 정리.
• config: Hatch config 조회/변경.
• dep: dependency 관련 보조 명령.
• check: project metadata 및 packaging 상태 검사.
• status: 현재 project/environment 상태 확인.
• self: Hatch 자체 관리.
• project: project metadata/workflow 관련 명령.
• lock: lock 관련 명령.

# 새 프로젝트 생성
hatch new my-app
 
# 기존 디렉터리를 Hatch 프로젝트로 초기화
cd existing-project
hatch new --init
 
# 기본 environment에서 python 실행
hatch run python -V
 
# 특정 environment에서 pytest 실행
hatch run test:pytest
 
# environment shell 진입
hatch shell
 
# 산출물 정리 후 build
hatch build --clean
 
# wheel만 build
hatch build -t wheel

• project 설정은 보통 pyproject.toml 에 들어간다.
• hatch.toml 파일을 사용할 수도 있으며, 이 경우 top-level key가 tool.hatch 하위 설정보다 우선할 수 있다.
• Hatch는 environment 진입과 명령 실행 시 project root로 이동하는 project-aware 동작을 기본으로 가진다.

hatch --help

Local `hatch` binary was not available in this workspace at edit time.
Capture live help later with:
 
hatch --help

• hatch: command not found: Hatch가 설치되지 않은 상태다. 공식 install 문서를 먼저 확인.
• shell startup completion이 필요하면 _HATCH_COMPLETE=bash_source hatch 또는 _HATCH_COMPLETE=zsh_source hatch 방식으로 completion script를 생성한다.
• hatch run 은 [ENV:]ARGS… 형식을 받으므로 test:pytest 같은 환경 접두어 사용 여부를 구분해야 한다.
• publish 전에는 hatch build 로 artifact를 먼저 확인하는 편이 안전하다.

• HATCH_ENV
• HATCH_PROJECT
• HATCH_VERBOSE
• HATCH_QUIET
• HATCH_CONFIG
• pyproject.toml
• hatch.toml

• python
• uv
• pip
• venv

• codex:: 2026-06-21 Created Hatch reference page with root options, command overview, and safe workflow examples.