Hatch reúne ambientes, scripts, versionamento e build de projetos Python. Sua configuração vive no pyproject.toml, o que ajuda a documentar tarefas sem uma coleção de comandos informais.
Configurar projeto e ambiente
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "exemplo-app"
version = "0.1.0"
requires-python = ">=3.12"
[tool.hatch.envs.test]
dependencies = ["pytest"]
[tool.hatch.envs.test.scripts]
run = "pytest -q {args:tests}"Depois de instalar Hatch em um ambiente de ferramentas, execute hatch run test:run. O ambiente é criado de forma isolada e o argumento padrão pode ser substituído na linha de comando.
Separar responsabilidades
O backend Hatchling constrói distribuições; o CLI Hatch orquestra tarefas. Essa distinção permite usar Hatchling sem obrigar todos os consumidores do pacote a instalar Hatch. Antes de publicar, execute hatch build, inspecione wheel e sdist e teste a instalação dos artefatos em ambiente limpo.
O guia de pyproject.toml explica os metadados, e uv para projetos Python oferece outra abordagem. Não combine ferramentas com funções sobrepostas sem definir qual delas controla lock, ambientes e build.
A documentação oficial do Hatch, consultada em 22 de julho de 2026, detalha ambientes, scripts e build. Fixe ferramentas na CI e nunca publique em um repositório real a partir de credenciais pessoais sem proteção e revisão.
Separar Hatch de Hatchling
Hatch é a ferramenta de projeto que cria ambientes, executa scripts, atualiza versões e inicia builds. Hatchling é um backend de build compatível com os padrões de empacotamento. O campo build-backend = "hatchling.build" informa a ferramentas como python -m build como produzir wheel e sdist; ele não obriga colaboradores nem consumidores a usar o comando hatch.
Essa separação evita acoplamento desnecessário. Um projeto pode padronizar tarefas com Hatch e ainda gerar artefatos instaláveis por pip. Também pode usar Hatchling como backend e outra ferramenta para ambientes. Escolha um responsável para cada função e registre a decisão.
Declarar metadados e layout
Para uma biblioteca com código em src/exemplo, declare os pacotes de forma explícita:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "exemplo-util"
version = "0.1.0"
description = "Utilitários para o projeto Exemplo"
readme = "README.md"
requires-python = ">=3.11"
dependencies = ["httpx>=0.27,<1"]
[tool.hatch.build.targets.wheel]
packages = ["src/exemplo"]O nome de distribuição pode conter hífen, enquanto o pacote importável normalmente usa um identificador Python. Confirme que o wheel contém módulos, tipagem e arquivos de dados necessários. Não inclua testes, segredos ou arquivos locais por acidente.
Organizar ambientes por finalidade
Ambientes independentes impedem que ferramentas de documentação vazem para a execução principal:
[tool.hatch.envs.test]
dependencies = [
"pytest",
"pytest-cov",
]
[tool.hatch.envs.test.scripts]
run = "pytest {args:tests}"
cov = "pytest --cov=exemplo --cov-report=term-missing {args:tests}"
[tool.hatch.envs.docs]
dependencies = ["sphinx"]
[tool.hatch.envs.docs.scripts]
build = "sphinx-build -W docs build/docs"Execute hatch run test:run ou passe um caminho depois do comando. Scripts curtos formam uma interface estável para desenvolvimento e CI. Evite esconder lógica complexa em uma linha TOML; mova fluxos extensos para um módulo Python testável.
Testar várias versões do Python
Matrizes verificam compatibilidade declarada:
[tool.hatch.envs.test]
matrix-name-format = "py{value}"
[[tool.hatch.envs.test.matrix]]
python = ["3.11", "3.12", "3.13"]Execute a matriz apenas para versões realmente suportadas. Se um interpretador não existir na máquina, instale-o conscientemente ou configure um provedor adequado. Uma execução ignorada não comprova compatibilidade. Na CI, faça a matriz visível para identificar qual versão falhou.
Versionar sem alterar o código manualmente
Hatch pode ler a versão de arquivo ou fonte configurada. Uma única fonte evita divergência entre pacote, metadados e documentação. Antes de automatizar incremento, decida se o projeto segue versionamento semântico e quem autoriza releases.
Não derive versões de estado Git sem considerar builds fora do repositório. Artefatos precisam ter versão determinística, e repetir o build do mesmo commit deve gerar metadados equivalentes.
Construir e inspecionar artefatos
hatch build cria wheel e sdist em dist/. Não publique imediatamente. Liste o conteúdo do wheel, extraia o sdist em diretório temporário e instale ambos em ambientes limpos. Rode ao menos um teste de importação e, para uma CLI, invoque --help.
hatch build
python -m pip install dist/exemplo_util-0.1.0-py3-none-any.whl
python -c "import exemplo; print(exemplo.__name__)"O nome exato do arquivo depende dos metadados. Em automação, descubra o artefato de maneira controlada e falhe se houver zero ou vários candidatos inesperados.
Publicar com fronteiras claras
Construção e publicação são etapas diferentes. A primeira pode ocorrer em todo pull request; a segunda deve rodar apenas para uma tag ou aprovação protegida. Use tokens de escopo mínimo e publicação confiável quando o repositório de pacotes oferecer essa opção. Nunca imprima credenciais em logs.
Comece por um índice de teste quando o fluxo ainda não foi validado. Confira nome, versão, descrição, arquivos e dependências na página resultante. Se a versão errada for publicada, normalmente não é possível substituir o mesmo número; corrija e publique uma nova versão conforme a política do índice.
Adotar Hatch sem confundir a equipe
Documente comandos essenciais no README: criar ambiente, rodar testes, gerar documentação e construir. Faça a CI chamar os mesmos scripts. Fixe a versão do Hatch usada pela automação ou adote uma política explícita de atualização.
Hatch traz mais valor quando substitui scripts divergentes por uma configuração compreensível. Ele não elimina a necessidade de revisar dependências, testar artefatos e proteger releases. Um projeto previsível deixa claro qual ferramenta resolve dependências, qual cria ambientes, qual constrói e quem pode publicar.