パッケージ管理したい（hatch）
// 新規プロジェクト作成
$ hatch new my-project
// 依存関係のインストール（pyproject.tomlの内容を反映）
$ hatch env create
// パッケージの実行とテスト
$ hatch run python main.py
$ hatch test
// コードチェック
$ hatch check
// バージョン管理
$ hatch version patch
// パッケージ公開
$ hatch build
$ hatch publish
hatchは、PyPA（Python Packaging Authority）傘下のプロジェクト管理ツールです。
プロジェクトの初期化、仮想環境の管理、テスト、コードチェック、パッケージのビルドと公開まで、Pythonプロジェクトのライフサイクル全体をカバーします。
pyproject.tomlを軸に設定し、複数のPython環境を自動で構築・管理できます。
バージョン管理コマンド（hatch version）を内蔵している点が、他のツールにはない特徴です。
注釈
Pythonでは、
パッケージ管理にはpip、
バージョン管理にはpyenv、
プロジェクト管理にはpoetry
のように、
複数のツールがまるで戦国時代のように群雄割拠しています。
hatchは、PyPAが管理する公式寄りのツールという立ち位置で、
とくにパッケージのビルド・公開まわり（hatchlingビルドバックエンド）で存在感があります。
uvやpoetryと比べると、
依存パッケージの追加・削除はpyproject.tomlを直接編集する運用が前提になっている点が特徴的です。
インストールしたい（hatch）
// Homebrewでインストール
$ brew install hatch
$ which -a hatch
/opt/homebrew/bin/hatch
$ hatch --version
Hatch, version 1.18.0
hatchはHomebrewでインストールできます。
pipx install hatchやuv tool install hatchでもインストールできます。
注釈
公式ドキュメントではpipxを使ったインストールが推奨されています。
挙動はどの方法でもほぼ同じで、専用の仮想環境を作ってから実行コマンドをPATHの通った場所にリンクします。
新規プロジェクトしたい（hatch new）
$ hatch new my-project
my-project
├── src
│ └── my_project
│ ├── __about__.py
│ └── __init__.py
├── tests
│ └── __init__.py
├── LICENSE.txt
├── README.md
└── pyproject.toml
hatch newコマンドでプロジェクトを初期化できます。
src/<パッケージ名>/レイアウトが自動生成され、__about__.pyにバージョン情報が保存されます。
authorやlicenseなどのメタデータは、Gitの設定（user.name、user.email）から自動で入力されます。
$ cat my-project/pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-project"
dynamic = ["version"]
description = ''
readme = "README.md"
requires-python = ">=3.8"
license = "MIT"
...
dependencies = []
[tool.hatch.version]
path = "src/my_project/__about__.py"
プロジェクトのメタデータはpyproject.tomlの[project]セクションに保存されます。
このファイルはユーザーが直接編集することを想定しています。
注釈
requires-pythonのデフォルトは>=3.8と古めです。
実際に使うPythonバージョンに合わせて、作成後に書き換えておくとよいです。
対話形式で作りたい（hatch new -i）
$ hatch new -i
Project name: my-project
Description []: サンプルプロジェクト
-i（--interactive）オプションで、プロジェクト名や説明などを対話的に入力しながら作成できます。
hatch new my-projectのように名前を直接指定する方法との違いは、対話中に説明文などの追加項目を入力できる点だけです。
既存ディレクトリに追加したい（hatch new --init）
$ cd my-project
$ hatch new --init
Project name: my-project
Description []:
Wrote: pyproject.toml
--initオプションで、既存のディレクトリにpyproject.tomlを追加できます。
プロジェクト名の入力を求められるので、ディレクトリ名などを入力してください。
hatch newと違って、src/レイアウトやREADME.md、LICENSE.txtは生成されず、pyproject.tomlのみが追加されます。
CLIツールを作りたい（hatch new --cli）
$ hatch new --cli my-cli-tool
--cliオプションで、コマンドラインインターフェイスを持つプロジェクトとして作成できます。
pyproject.tomlの[project.scripts]にエントリーポイントが自動登録されます。
仮想環境したい（hatch env）
$ cd my-project
// 仮想環境を作成
$ hatch env create
Creating environment: default
Installing project in development mode
Checking dependencies
// 環境一覧を確認
$ hatch env show
Standalone
┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name ┃ Type ┃ Dependencies ┃ Scripts ┃
┡━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ default │ virtual │ │ │
└─────────┴─────────┴──────────────┴─────────┘
// 環境の保存先を確認
$ hatch env find
~/.local/share/hatch/env/virtual/my-project/xxxxxxxx/my-project
hatch env createコマンドで仮想環境を明示的に作成できます。
hatch shellやhatch runを実行したときにも、環境がなければ自動的に作成されます。
hatch env showで作成済みの環境一覧、hatch env findで環境の実際の保存先を確認できます。
デフォルトの保存先はプロジェクトディレクトリの外（~/.local/share/hatch/env/配下）です。
.venvのようにプロジェクト内に作られるuv venvやpoetry env（virtualenvs.in-project設定時）とは異なる点に注意してください。
// 仮想環境の中に入る
$ hatch shell
You are about to enter a new shell, exit as you usually would e.g. by typing `exit` or pressing `ctrl+d`...
(my-project) $ exit
hatch shellコマンドで、仮想環境をアクティブ化したサブシェルに入れます。
uv venvやpoetry env activateと違って、sourceコマンドを使わずに直接シェルへ入れる点が特徴です。
抜けるときはexitかCtrl+Dを使います。
// 環境を削除
$ hatch env remove
Removing environment: default
// すべての環境を削除
$ hatch env prune
hatch env removeコマンドで、現在の環境を削除できます。
hatch env pruneコマンドで、プロジェクトに紐づくすべての環境（テスト用・ビルド用なども含む）を一括削除できます。
注釈
hatch env showはデフォルトで、ユーザーがpyproject.tomlの[tool.hatch.envs.*]で定義した環境のみを表示します。
hatch testやhatch buildが内部的に使う環境（hatch-test、hatch-buildなど）も見たい場合は、-i（--internal）オプションを付けます。
依存関係を管理したい（pyproject.toml）
1[project]
2dependencies = [
3 "requests>=2.28.0",
4]
hatchには、uv addやpoetry addに相当する「パッケージ追加」専用コマンドがありません。
pyproject.tomlのdependenciesを直接編集してから、hatch env create（やhatch run）で環境に反映する運用が前提です。
// 現在の依存関係を確認
$ hatch dep show requirements
requests>=2.28.0
hatch dep show requirementsコマンドで、現在定義されている依存関係をrequirements.txt形式で確認できます。
注釈
[project]セクションのdependenciesはプロジェクト全体の依存関係です。
[tool.hatch.envs.<環境名>]セクションにdependenciesを追加すると、その環境だけに依存パッケージを追加できます。
テスト専用のパッケージなどは、後者で環境ごとに分けておくと管理しやすいです。
ロックファイルを使いたい（hatch dep lock）
1[tool.hatch.envs.default]
2locked = true
3installer = "uv"
hatch dep lockコマンドで、PEP 751形式のロックファイル（pylock.toml）を生成できます。
uv.lockやpoetry.lockと違って、環境ごとにlocked = trueを明示しないと有効になりません。
またhatch dep sync（ロックファイルの内容を環境に反映するコマンド）を使うには、installer = "uv"の指定も必要です（デフォルトのpipインストーラーは未対応）。
$ hatch dep lock
Locking environment: default
$ hatch dep sync
Syncing from lockfile
Synced environment `default` from `pylock.toml`
注釈
この機能は2026年時点でもまだ実験的な位置づけです。
uvやpoetryのように「デフォルトでロックファイルを使う」運用ではなく、hatchはオプトインの機能として提供しています。
再現性を重視しないプロジェクトでは、ロック機能を使わずにdependenciesの直接編集だけで運用しても問題ありません。
パッケージを実行したい（hatch run）
$ hatch run python main.py
Hello, World!
$ hatch run pytest
===== test session starts =====
tests/test_example.py . [100%]
1 passed
hatch runコマンドで、プロジェクトの仮想環境を使って外部コマンドやスクリプトを実行できます。
仮想環境の手動アクティベーションは不要です。
1[tool.hatch.envs.default.scripts]
2format = "ruff format ."
3lint = "ruff check ."
pyproject.tomlの[tool.hatch.envs.<環境名>.scripts]に、よく使うコマンドをエイリアスとして登録できます。
$ hatch run format
$ hatch run lint
登録したエイリアスは、hatch run <エイリアス名>で実行できます。
// 環境名を指定して実行
$ hatch run types:check
環境名:コマンドの形式で、default以外の環境を指定して実行できます。
環境を省略した場合は、-eオプション（やHATCH_ENV環境変数）で指定した環境、それもなければdefault環境が使われます。
コードをチェックしたい（hatch check）
$ hatch check
hatch checkコマンドで、静的解析（lint）・フォーマット確認・型チェックをまとめて実行できます。
内部ではRuffや型チェッカーを利用しています。
// 自動修正を適用
$ hatch check --fix
// リンターのみ実行
$ hatch check code
// フォーマット確認のみ実行
$ hatch check fmt
// 型チェックのみ実行
$ hatch check types
--fixオプションで、自動修正できる問題を書き換えられます。
code（静的解析）、fmt（フォーマット確認）、types（型チェック）のサブコマンドで、個別に実行することもできます。
注釈
過去バージョンにあったhatch fmtコマンドは、hatch 1.18.0時点では非推奨になっています。
実行するとhatch check code --fixとhatch check fmt --fixを使うよう案内されます。
既存のドキュメントや記事でhatch fmtを見かけたら、hatch check --fixに読み替えてください。
テストしたい（hatch test）
$ hatch test
============================= test session starts ==============================
platform darwin -- Python 3.12.7, pytest-9.1.1, pluggy-1.6.0
...
tests/test_example.py . [100%]
============================== 1 passed in 0.01s ===============================
hatch testコマンドで、専用のhatch-test環境を使ってテストを実行できます。
pytestやcoverageなどのテスト用パッケージがあらかじめ含まれており、手動でのインストールは不要です。
デフォルトでは、現在使用中のインタープリターに一致する環境1つだけでテストが実行されます。
複数のPythonバージョンでテストしたい場合は、pyproject.tomlでマトリクスを定義します。
1[[tool.hatch.envs.hatch-test.matrix]]
2python = ["3.11", "3.12", "3.13"]
// マトリクスに定義したすべてのバージョンでテスト
$ hatch test --all
// 特定のバージョンだけテスト
$ hatch test --python 3.12
// カバレッジを測定
$ hatch test --cover
// 並列実行
$ hatch test --parallel
--allオプションで、マトリクスに定義したすべてのバージョンでテストを実行できます。
指定しない場合は、現在の環境に合う1つのバージョンのみが対象になる点に注意してください。
バージョンを管理したい（hatch version）
$ hatch version
0.0.1
$ hatch version patch
Old: 0.0.1
New: 0.0.2
$ hatch version minor
Old: 0.0.2
New: 0.1.0
$ hatch version major
Old: 0.1.0
New: 1.0.0
hatch versionコマンドで、プロジェクトのバージョンを確認・更新できます。
バージョン情報はhatch newで生成されるsrc/<パッケージ名>/__about__.pyに保存され、pyproject.tomlの[tool.hatch.version]がその参照先を指定しています。
hatch version patch：パッチバージョンを上げる（バグ修正）hatch version minor：マイナーバージョンを上げる（新機能）hatch version major：メジャーバージョンを上げる（大きな変更）
注釈
uvやpoetryには、これに相当するバージョン管理コマンドがありません（uv versionはサブコマンドとして未提供、poetry versionは別途存在しますがhatchほど__about__.pyとの連携は強くありません）。
バージョンを頻繁にバンプする運用であれば、hatchならではの利点になります。
パッケージをビルドしたい（hatch build）
$ hatch build
sdist
dist/my_project-0.0.2.tar.gz
wheel
dist/my_project-0.0.2-py3-none-any.whl
hatch buildコマンドでパッケージをビルドできます。
dist/ディレクトリの中に、wheel形式（.whl）とsdist形式（.tar.gz）のファイルが生成されます。
$ hatch build --target wheel
Inspecting build dependencies
──────────────────────────────────── wheel ─────────────────────────────────────
dist/my_project-0.0.2-py3-none-any.whl
$ hatch build --target sdist
Inspecting build dependencies
──────────────────────────────────── sdist ─────────────────────────────────────
dist/my_project-0.0.2.tar.gz
-t（--target）オプションで、どちらか片方の形式だけをビルドできます。
注釈
uv buildやpoetry buildにある--dry-runのようなオプションは、hatch buildにはありません。
実際に手を動かす前に内容を確認したい場合は、-c（--clean）オプションを付けずに実行し、生成されたdist/の中身を確認するのが実用的です。
パッケージを公開したい（hatch publish）
$ hatch publish
Enter your username: __token__
Enter your credentials:
hatch publishコマンドで、PyPIにパッケージを公開できます。
認証情報が未設定の場合は、初回実行時にユーザー名（__token__固定）とAPIトークンの入力を求められます。
一度入力すると、~/.config/hatch/config.toml（プラットフォームによって異なる）に保存され、以降は再入力不要です。
// TestPyPIに公開
$ hatch publish -r test
-r（--repo）オプションで、公開先を切り替えられます。
testは組み込みのエイリアスで、TestPyPIを指します（mainがデフォルトのPyPI）。
はじめて公開するパッケージは、まずTestPyPIに公開して動作テストしてからPyPIに本番公開することをオススメします。
// ユーザー名・トークンをオプションで直接指定
$ hatch publish -u __token__ -a <your-token>
-u（--user）・-a（--auth）オプションで、認証情報をコマンドラインから直接渡せます。
CI環境では、HATCH_INDEX_USER・HATCH_INDEX_AUTH環境変数で渡すほうが安全です。
注釈
uv publishやpoetry publishにある--dry-runのようなオプションは、hatch publishにもありません。
公開前の確認は、hatch buildで生成したdist/の中身を目視するか、TestPyPIへの公開で代用してください。
注釈
PyPIとTestPyPIは、サービスとしては別物です。 それぞれのサービスでアカウントを作成してください。 また、プロジェクトごとにAPIトークンを発行してください。
注意
PyPIとTestPyPIには、同じ名前のパッケージは登録できません。 プロジェクトを作成する段階で、パッケージ名の重複がないか確認してください。 また、同じバージョンの再アップロード（上書き）もできません。 変更内容に応じてバージョンを更新してください。