On this page

Packaging & Distribution

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

Why Packaging Matters​

Packaging is the process of turning your Python project into an installable, versioned, and distributable package.

It enables:

Modern Python packaging uses pyproject.toml, build backends, and wheel distributions.

This lesson teaches you how to package a project correctly and professionally.


Standard Project Structure​

A clean, modern package layout:


yourproject/

    pyproject.toml

    README.md

    LICENSE

    src/

        yourproject/

            __init__.py

            module_a.py

            module_b.py

    tests/

        test_module_a.py

Key points:

This structure is now the recommended standard.


The pyproject.toml File​

pyproject.toml defines:

A minimal example:


[project]

name = "yourproject"

version = "0.1.0"

description = "A sample Python package"

authors = [{ name = "Enrico" }]

readme = "README.md"

requires-python = ">=3.10"

dependencies = []



[build-system]

requires = ["setuptools>=61.0"]

build-backend = "setuptools.build_meta"

This replaces the old setup.py and setup.cfg approach.


Adding Dependencies​

Declare runtime dependencies:


[project]

dependencies = [

    "requests>=2.0",

    "numpy>=1.26"

]

These are installed automatically when users install your package.


Writing the Package Code​

Inside src/yourproject/module_a.py:


def greet(name: str) -> str:

    return f"Hello, {name}"

Inside src/yourproject/__init__.py:


from .module_a import greet

This exposes a clean public API.


Building the Distribution​

Use the modern build tool:


python -m pip install build

python -m build

This produces:

Both appear in the dist/ directory.


Installing Your Package Locally​

Test installation before publishing:


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

Or install in editable mode during development:


pip install -e .

Editable installs allow live code changes without reinstalling.


Publishing to PyPI​

First install the upload tool:


pip install twine

Upload:


twine upload dist/*

You will need:

After uploading, anyone can install your package:


pip install yourproject

Versioning Best Practices​

Follow semantic versioning:

Example:

Clear versioning builds trust and predictability.


Including Metadata​

Good packages include:

Metadata improves discoverability and professionalism.


Testing Your Package​

Use a dedicated test directory:


tests/

    test_module_a.py

Example test:


from yourproject import greet



def test_greet():

    assert greet("Alice") == "Hello, Alice"

Run tests with:


pytest

Testing ensures reliability before distribution.


Best Practices​

These practices align with modern Python packaging standards.


Summary​

Packaging and distribution turn your Python code into a professional, installable, and shareable package.

You learned how to structure a project, configure pyproject.toml, build wheels, publish to PyPI, manage dependencies, and follow best practices for maintainable, distributable software.

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Virtual Environments

Next

Guided Exercise: Build a Python Package