- Courses
- 💻Programming Languages
- 🐍Python
- Intermediate Python & Best Practices
- Packaging & Distribution
On this page
Packaging & Distribution
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:
- Clean installation with
pip install yourpackage - Versioning and dependency management
- Sharing code across teams or the public
- Publishing to PyPI
- Professional project organization
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:
src/layout prevents accidental imports from the working directoryyourproject/is the actual package__init__.pymarks it as a package- Tests live outside the package code
This structure is now the recommended standard.
The pyproject.toml File
pyproject.toml defines:
- Build system
- Package metadata
- Dependencies
- Optional tools (formatters, linters, type checkers)
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:
- A wheel file (
.whl) — the preferred binary distribution - A source distribution (
.tar.gz) — the raw source package
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:
- A PyPI account
- An API token
After uploading, anyone can install your package:
pip install yourproject
Versioning Best Practices
Follow semantic versioning:
MAJOR.MINOR.PATCH- Increment PATCH for bug fixes
- Increment MINOR for new features
- Increment MAJOR for breaking changes
Example:
1.0.0— stable release1.1.0— new features2.0.0— breaking changes
Clear versioning builds trust and predictability.
Including Metadata
Good packages include:
README.md— project overviewLICENSE— legal clarityCHANGELOG.md— version historypyproject.toml— metadata and configuration
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
- Use the
src/layout for clean imports - Keep
pyproject.tomlas the single source of truth - Write a clear README and license
- Use semantic versioning
- Build wheels, not just source distributions
- Test before publishing
- Avoid unnecessary dependencies
- Keep your public API stable and documented
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!
Previous
Virtual Environments
Next
Guided Exercise: Build a Python Package
- Why Packaging Matters
- Standard Project Structure
- The
pyproject.tomlFile - Adding Dependencies
- Writing the Package Code
- Building the Distribution
- Installing Your Package Locally
- Publishing to PyPI
- Versioning Best Practices
- Including Metadata
- Testing Your Package
- Best Practices
- Summary
