Install Hatchling for Python Packaging

Hatchling is a modern build backend for Python. It helps you turn your source code into installable packages. Many developers now prefer it over older tools.

This guide shows you how to install Hatchling and use it in a real project. You will also learn how to build wheels and source distributions.

What Is Hatchling?

Hatchling is the build backend that powers the Hatch project manager. A build backend is the tool that creates your package files.

It reads a file called pyproject.toml. That file describes your project. Then Hatchling builds a wheel or a source archive for you.

Hatchling is fast, standards-based, and easy to configure. It follows PEP 517 and PEP 621. This means it works well with modern Python packaging tools.

Why Use Hatchling?

There are several good reasons to pick Hatchling for your next project.

First, it is lightweight. You only install what you need to build your package.

Second, it supports dynamic metadata. You can pull the version number from a file or a variable.

Third, it plays nicely with pip and build. You do not need extra plugins in most cases.

Finally, it is well maintained. The project keeps up with new Python packaging standards.

Prerequisites

Before you start, make sure you have a few things ready.

You need Python 3.7 or newer. You also need pip installed. Most Python installs include it by default.

It is a good idea to work inside a virtual environment. This keeps your project dependencies separate from your system Python.

You can create one with the venv module. Run the command below in your terminal.

python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

Once the environment is active, you are ready to install Hatchling.

How to Install Hatchling

Installing Hatchling is simple. You can use pip to add it to your environment.

Run this command in your terminal:

pip install hatchling

After the install finishes, you can confirm it worked. Check the installed version with this command:

pip show hatchling

You should see output like this:

Name: hatchling
Version: 1.25.0
Summary: Modern, extensible Python build backend
Home-page: https://hatch.pypa.io/latest/
Author: Ofek Lev
License: MIT

If you see a version number, the install worked. Now you can use Hatchling in your project.

Setting Up a Project with Hatchling

Hatchling needs a pyproject.toml file. This file lives in the root of your project.

Let us create a small example project. First, make a new folder and move into it.

mkdir myproject
cd myproject

Next, create a package folder with an __init__.py file. This marks it as a Python package.

mkdir mypackage
touch mypackage/__init__.py

Now create the pyproject.toml file. Add the content below.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "mypackage"
version = "0.1.0"
description = "A small example package"
readme = "README.md"
requires-python = ">=3.8"
authors = [
    { name = "Your Name", email = "[email protected]" },
]

The [build-system] section tells tools like pip to use Hatchling. The [project] section holds your package metadata.

Make sure the name matches your package folder. In this case, the folder is mypackage.

Building Your Package

Now that the config is ready, you can build your package. Install the build tool first.

pip install build

Then run the build command from your project root.

python -m build

Hatchling will create two files inside a new dist folder. You should see output similar to this:

* Creating venv isolated environment...
* Installing packages in isolated environment... (hatchling)
* Getting build dependencies for sdist...
* Building sdist...
* Building wheel from sdist
* Creating venv isolated environment...
* Installing packages in isolated environment... (hatchling)
* Getting build dependencies for wheel...
* Building wheel...
Successfully built mypackage-0.1.0.tar.gz and mypackage-0.1.0-py3-none-any.whl

The .whl file is a wheel. The .tar.gz file is a source distribution. Both are ready to share or upload.

Using Dynamic Versioning

Hardcoding the version works, but it can cause mistakes. Hatchling supports dynamic versioning instead.

You can read the version from your package's __init__.py file. Update your pyproject.toml like this.

[project]
name = "mypackage"
dynamic = ["version"]

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

Then set the version inside mypackage/__init__.py.

__version__ = "0.1.0"

Now Hatchling reads the version from that file. You only update it in one place.

Common Installation Issues

Sometimes the install does not go as planned. Here are a few common problems.

If you see a permission error, your environment may not be active. Activate your virtual environment and try again.

If pip is outdated, upgrades can fail. Run pip install --upgrade pip to fix it.

If the build fails with a missing backend error, check your pyproject.toml. The build-backend line must be exactly hatchling.build.

Also make sure your package name matches the folder name. A mismatch is a very common mistake.

Testing Your Package Locally

Before you publish anything, test the wheel. Install it into a fresh environment.

pip install dist/mypackage-0.1.0-py3-none-any.whl

Then open a Python shell and import your package.

import mypackage
print(mypackage.__version__)

You should see the version number printed.

0.1.0

If that works, your package is built correctly. You are ready to publish it to PyPI.

Hatchling vs Other Backends

You may wonder how Hatchling compares to setuptools or flit.

Setuptools is older and very flexible. But its config can be complex for new projects.

Flit is simple and great for pure Python packages. It has fewer features than Hatchling.

Hatchling sits in the middle. It is simple to start with, yet powerful enough for larger projects. It also supports plugins and custom build hooks.

Conclusion

Installing Hatchling for Python packaging is quick and easy. One pip install hatchling command is all it takes.

From there, you add a pyproject.toml file. You set the build backend to Hatchling. Then you run python -m build to create your wheel and source files.

Hatchling is fast, modern, and standards-based. It is a great choice for both small scripts and large libraries.

Follow the steps in this guide. Test your wheel locally. Then publish your package with confidence.