Getting Started

This tutorial will guide you through installing build and creating your first Python package ready for distribution.

Note

New to Python packaging? Start with the Python Packaging User Guide tutorial to learn how to structure a Python project. This tutorial assumes you already have a project with a pyproject.toml file.

Prerequisites

You need Python 3.9 or later installed on your system. Check your Python version:

$ python --version
Python 3.11.0

Installation

The recommended way to install build is using pip:

$ pip install build

Or, if you prefer to install it in an isolated environment using pipx:

$ pipx install build

For corporate environments or systems with restricted internet access, see Corporate Environments.

Creating a simple package

Let’s create a minimal Python package to demonstrate how build works.

  1. Create a project directory:

$ mkdir mypackage
$ cd mypackage

  1. Create a pyproject.toml file:

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

[project]
name = "mypackage"
version = "0.1.0"
description = "A simple example package"
readme = "README.md"
requires-python = ">=3.8"

  1. Create a README.md file:

# My Package

This is a simple example package.

  1. Create your Python package:

$ mkdir src/mypackage
$ touch src/mypackage/__init__.py

  1. Add some code to src/mypackage/__init__.py:

def hello():
    return "Hello from mypackage!"

Building your package

Now you’re ready to build your package:

$ python -m build

You should see output like:

* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - hatchling
* Getting build dependencies for sdist...
* Building sdist...
* Building wheel from sdist
* Creating isolated environment: venv+pip...
* 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 built packages are now in the dist/ directory:

$ ls dist/
mypackage-0.1.0-py3-none-any.whl
mypackage-0.1.0.tar.gz

Understanding what happened

Build created two distribution files (packages ready for distribution):

  1. Source distribution: mypackage-0.1.0.tar.gz

    This tarball (compressed archive) contains your source code. Anyone can download it and build your package on their system. Learn more in the source distribution specification.

  2. Wheel: mypackage-0.1.0-py3-none-any.whl

    This wheel is a pre-built package that pip can install directly without needing to build anything. This makes installation much faster.

Build used an isolated environment to ensure your package builds consistently regardless of what you have installed on your computer. It:

  1. Created a temporary virtual environment

  2. Installed only your build dependencies (hatchling)

  3. Invoked the build backend to create the distribution files

  4. Cleaned up the temporary environment when done

Next steps