Why I Finally Switched to Hatch for Python Builds

Actually, I should clarify — I’ve spent the last decade fighting with Python packaging. I’ve written setup.py files that looked like spaghetti code. I’ve dealt with requirements.txt files that somehow worked on my machine but exploded in CI. I’ve used Poetry, Flit, PDM, and raw setuptools. And honestly? Most of them made me want to quit programming and become a goat farmer.

But around late 2024, I forced myself to try Hatch. Not just for a toy project, but for a messy, dependency-heavy internal tool we use for data processing. It was painful at first—mostly because I had to unlearn years of bad habits—but now, in February 2026, I can’t imagine going back.

For the longest time, Python didn’t really have a standard. We had “recommendations” that everyone ignored. But with PEP 621 (standardizing metadata) and PEP 517 (build backends), things finally stabilized. Hatch—specifically its build backend, Hatchling—feels like the first tool that actually respects these standards without adding a layer of proprietary nonsense on top.

I recently migrated a legacy library from setuptools to Hatch. The setup.py was 180 lines of imperative Python logic just to include some non-code data files. The replacement pyproject.toml? 34 lines. That’s not an exaggeration. It’s just declarative configuration. It works or it doesn’t.

Hatch manages environments for you, but it does it with a “matrix” approach that is incredibly useful for testing. Instead of just one environment, you can define environment types. I was debugging a weird segfault that only happened on Python 3.13 (which is our production target as of last month). I didn’t want to blow up my main dev environment. So I added this:

[tool.hatch.envs.test]
dependencies = [
  "pytest",
  "pytest-cov",
]

[[tool.hatch.envs.test.matrix]]
python = ["3.11", "3.12", "3.13"]

Then I ran:

hatch run test:pytest

Hatch spun up three isolated environments, ran the tests in all of them, and reported back. I didn’t have to install Docker. I didn’t have to configure Tox (which I’ve always found clunky). It just worked. It felt like I was cheating.

Hatch has a built-in version command that hooks into your code. I configure it to look at a file:

[tool.hatch.version]
path = "src/cruncher/__init__.py"

Now, when I’m ready to release, I just type:

hatch version minor

It updates the file. It’s simple, but it removes one more friction point. And removing friction is the only way you actually ship things instead of sitting on them.

Look, tools are just a means to an end. The goal is to get your code out of your repo and into the hands of users. If your build system is so complex that you dread releasing a new version, your project is already dying. As I’ve argued before, deployment should be boring.

Hatch isn’t perfect. The documentation can be a bit dense sometimes, and I’ve hit a few edge cases with C-extensions that required some fiddling. But compared to the absolute chaos of the last ten years of Python packaging, it’s a breath of fresh air.

It lets me define my project, test it across versions, and build the artifact without having to think about the plumbing. And that means I can stop tweaking config files and actually ship the feature I promised three months ago.

Frequently asked questions

How does Hatch’s environment matrix compare to Tox for testing across Python versions?

Hatch uses a declarative matrix in pyproject.toml where you list Python versions like 3.11, 3.12, and 3.13 under tool.hatch.envs.test.matrix. Running hatch run test:pytest spins up isolated environments and runs tests in each automatically. The author found this cleaner than Tox, which they describe as clunky, and it avoids needing Docker to reproduce version-specific bugs like a Python 3.13 segfault.

How many lines does a pyproject.toml replace when migrating from setup.py to Hatch?

In the author’s migration of a legacy library, a 180-line setup.py containing imperative Python logic for including non-code data files was replaced by a 34-line pyproject.toml. The reduction comes from Hatchling’s declarative configuration approach, which respects PEP 621 metadata and PEP 517 build backend standards rather than requiring custom imperative code. It either works or it doesn’t—no spaghetti logic needed.

How do you bump the version number in a Hatch project?

Hatch includes a built-in version command that reads from a file you configure under [tool.hatch.version] with a path like src/cruncher/__init__.py. Running hatch version minor updates the file automatically. The author uses this to remove release friction, arguing that simple, boring deployment is what actually lets you ship code instead of letting releases pile up indefinitely.

Is Hatchling compliant with PEP 517 and PEP 621 Python packaging standards?

Hatchling, Hatch’s build backend, is described as the first tool that genuinely respects PEP 621 (standardizing project metadata) and PEP 517 (build backends) without layering proprietary conventions on top. Before these PEPs, Python packaging relied on widely-ignored recommendations, but Hatchling’s adherence to the standards is what made the author finally trust it for a messy, dependency-heavy internal data processing tool.