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

Python packaging and distribution is the process of organizing your code in a way that others can easily install, reuse, and integrate it into their own projects. This is essential when you want to share your library, deploy applications, or maintain clean project structures across teams.

1. What is Python Packaging?

Packaging means structuring your Python project so it can be treated as a reusable module or library. Instead of sharing raw .py files, you bundle everything—code, dependencies, metadata—into a standardized format.

A typical Python package includes:

  • Source code (organized in folders with __init__.py)

  • Metadata (name, version, author)

  • Dependency list

  • Instructions for installation

This allows users to install your package using tools like pip.

2. Role of setup.py

The setup.py file is the traditional configuration script used to define your package. It tells Python how to build, install, and distribute your project.

A basic example:

from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="1.0.0",
    packages=find_packages(),
    install_requires=[
        "requests",
    ],
    author="Your Name",
    description="A simple Python package"
)

Key components:

  • name: Package name used during installation

  • version: Helps manage updates

  • packages: Automatically finds sub-packages

  • install_requires: Lists dependencies

  • description: Brief explanation of the package

Although newer standards like pyproject.toml are becoming more popular, setup.py is still widely used and important to understand.

3. What are Wheels?

A wheel is a built distribution format for Python packages. It is essentially a pre-compiled version of your package that can be installed quickly.

File format:

mypackage-1.0.0-py3-none-any.whl

Advantages of wheels:

  • Faster installation (no need to compile code)

  • Platform compatibility (specific builds for Windows, Linux, etc.)

  • Reduces errors during installation

You can create a wheel using:

python setup.py bdist_wheel

This generates a .whl file inside a dist/ directory.

4. Source Distribution (sdist)

Along with wheels, you can also create a source distribution:

python setup.py sdist

This produces a .tar.gz file containing your raw source code. When users install it, the code is compiled on their system.

5. Python Package Index (PyPI)

PyPI is the official repository where Python packages are published and shared. It allows developers worldwide to install packages using:

pip install package_name

To upload your package to PyPI:

  1. Build your package:

    python setup.py sdist bdist_wheel

  2. Upload using a tool like twine:

    twine upload dist/*

Once uploaded, your package becomes publicly accessible.

6. Versioning and Dependency Management

Versioning is critical in packaging. It follows a standard format:

MAJOR.MINOR.PATCH

Example:

  • 1.0.0 → Initial release

  • 1.1.0 → Added new features

  • 1.1.1 → Bug fixes

Dependencies can also be version-controlled:

install_requires=[
    "requests>=2.25.0,<3.0.0"
]

This ensures compatibility and stability.

7. Modern Packaging (pyproject.toml)

Modern Python packaging is shifting toward pyproject.toml, which separates build configuration from execution.

Example:

[project]
name = "mypackage"
version = "1.0.0"
dependencies = ["requests"]

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

This approach is cleaner and more standardized compared to setup.py.

8. Why Packaging Matters

  • Enables code reuse across projects

  • Simplifies installation for users

  • Supports collaboration and open-source contributions

  • Makes deployment easier in production environments

  • Helps maintain version control and dependency consistency

9. Real-World Use Case

If you build a utility library for data processing, instead of copying code into multiple projects, you can:

  1. Package it properly

  2. Upload it to PyPI

  3. Install it anywhere using pip

This saves time and ensures consistency across applications.

Conclusion

Python packaging and distribution transform your code from a simple script into a professional, reusable product. Understanding tools like setup.py, wheels, and PyPI allows you to share your work efficiently, maintain clean project structures, and follow industry best practices.