Packaging Best Practices

Rules for packages that install cleanly, version predictably, and publish safely.

How to Use This List

• Apply when creating a new package or preparing a release
• Libraries follow stricter rules than internal applications
• Review before every PyPI publish

A - Project Structure

• src/ layout. Tests import the installed package.
• pyproject.toml only. No setup.py, setup.cfg, or requirements.txt as source of truth.
• hatchling build backend. Unless extensions require maturin/setuptools.
• README on PyPI. readme = "README.md" in [project].

B - Metadata

• Clear name and description. Searchable on PyPI.
• requires-python set. Match actual supported versions.
• License declared. SPDX identifier in [project].
• Classifiers accurate. Python version, OS, framework tags.

C - Versioning & Releases

• SemVer for libraries. MAJOR for breaking, MINOR for features, PATCH for fixes.
• CHANGELOG updated. Every release documented.
• Git tag matches version. v1.2.3 tag for 1.2.3 release.
• TestPyPI first. Verify install before production PyPI.

D - Build & Publish

• Build in CI. Reproducible artifacts from clean environment.
• Test the wheel. pip install dist/*.whl in fresh venv before upload.
• Trusted publishing. OIDC tokens, not passwords in CI.
• Both wheel and sdist. Publish both formats.

E - Security

• No secrets in package. Tokens, keys, and passwords never in source or metadata.
• Minimal dependencies. Fewer deps = smaller attack surface.
• Yank, don't delete. Bad releases yanked on PyPI with explanation.
• 2FA on PyPI account. Required for all publishers.

FAQs

Related

• Packaging Basics - getting started
• Publishing to PyPI - upload workflow
• Versioning & Changelogs - release notes
• Environments Best Practices - dependency management

Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.