Python - Packaging & Distribution in Python (pip, setup.py, wheels)

Packaging and distribution is the process of turning your Python code into a reusable, installable project that others (or you, on another machine) can easily use. Instead of sharing raw .py files, you bundle your code into a structured format and distribute it via tools like pip.

1. What is Python Packaging?

Python packaging means organizing your code into a standard structure so it can be installed, versioned, and reused. A packaged project is called a distribution.

There are two main types:

  • Source distribution (sdist): Contains your raw source code

  • Built distribution (wheel): Pre-built format for faster installation

2. Project Structure

A typical Python package looks like this:

my_project/
│
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
│
├── tests/
├── README.md
├── LICENSE
├── pyproject.toml
└── setup.py (optional in modern packaging)

Key points:

  • The folder with __init__.py is treated as a package

  • pyproject.toml is now the modern standard (replacing many uses of setup.py)

3. setup.py (Traditional Method)

Earlier, packaging was done using a setup.py file:

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1",
    packages=find_packages(),
    install_requires=[
        "requests"
    ],
)

This file defines:

  • Package name and version

  • Dependencies

  • Included modules

Although still used, modern Python prefers pyproject.toml.

4. pyproject.toml (Modern Standard)

This is now the recommended way to define build configuration:

[project]
name = "my_package"
version = "0.1.0"
dependencies = ["requests"]

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

Advantages:

  • Cleaner and standardized

  • Works across different build tools

  • Required for modern packaging tools

5. pip (Package Installer)

pip is the tool used to install Python packages.

Examples:

Install a package:

pip install requests

Install your own package locally:

pip install .

Install in editable mode (for development):

pip install -e .

pip reads your project metadata and installs dependencies automatically.

6. Building Distributions

To distribute your package, you build it into distributable formats.

Install build tool:

pip install build

Then run:

python -m build

This generates:

  • .tar.gz (source distribution)

  • .whl (wheel file)

7. Wheels (Built Distributions)

A wheel is a precompiled package format.

Example:

my_package-0.1.0-py3-none-any.whl

Benefits:

  • Faster installation (no need to build)

  • Platform-specific optimizations possible

  • Preferred format for distribution

8. Publishing Packages

You can publish your package to a public repository so others can install it.

Most common repository:

  • PyPI (Python Package Index)

Steps:

  1. Create an account on PyPI

  2. Install upload tool:

    pip install twine

  3. Upload:

    twine upload dist/*

After publishing, anyone can install your package using pip.

9. Versioning

Packages use version numbers like:

1.0.0

Standard format:

MAJOR.MINOR.PATCH

  • MAJOR: Breaking changes

  • MINOR: New features

  • PATCH: Bug fixes

This helps users manage compatibility.

10. Dependency Management

You define required libraries in:

  • pyproject.toml (modern)

  • or install_requires in setup.py

Example:

dependencies = ["numpy", "pandas"]

pip installs these automatically when your package is installed.

11. Why Packaging is Important

  • Makes code reusable and shareable

  • Simplifies installation for others

  • Helps manage dependencies properly

  • Required for professional and production-level development

  • Enables publishing libraries used by thousands of developers

Summary

Packaging and distribution turns your Python code into a structured, installable product. Tools like pip, build systems, and formats like wheels ensure that your code can be easily shared, installed, and maintained across different environments.