Mastering Python Package Versioning: A Practical Guide to PEP 440

Basic version format

PEP 440 defines version numbers composed of major, minor, patch, and optional pre‑release, development, or post‑release identifiers.

<major>.<minor>.<patch>[.<pre‑release>|.<dev‑release>|.<post‑release>]

Major : indicates incompatible API changes.

Minor : indicates backward‑compatible feature additions.

Patch : indicates backward‑compatible bug fixes.

Pre‑release : alpha, beta, or release candidate (rc) versions.

Development release : marks in‑development builds.

Post‑release : used for urgent fixes after a final release.

Pre‑release versions

Pre‑releases are used for testing before an official release.

<major>.<minor>.<patch>aN
<major>.<minor>.<patch>bN
<major>.<minor>.<patch>rcN

Here aN denotes an alpha version, bN a beta version, and rcN a release‑candidate version, where N starts at 1 and increments.

Development releases

Development releases identify versions that are still under active development.

<major>.<minor>.<patch>.devN

N

starts at 0; for example, 1.0.0.dev1 is the first development build of version 1.0.0.

Post‑release versions

Post‑releases are used for urgent fixes after a final release. <major>.<minor>.<patch>.postN Example: 1.0.0.post1 denotes the first post‑release of version 1.0.0.

Local version identifiers

Local identifiers distinguish builds in a specific environment.

<major>.<minor>.<patch>+<local>

Example: 1.0.0+local.1 represents local version 1 of 1.0.0.

Version comparison rules

Major, minor, and patch numbers are compared numerically.

Pre‑release versions are ordered before the final release.

Development releases are ordered before pre‑releases.

Post‑releases are ordered after development releases.

Practical benefits

Dependency management : Clear version numbers help avoid conflicts.

Version control : Standardized numbers improve VCS tracking of releases.

Release workflow : Using pre‑ and post‑releases enables smoother planning and execution of releases.

Examples

1.0.0

: first official release. 1.0.1: bug‑fix release for the first official version. 1.1.0: adds new features while remaining backward compatible. 2.0.0: introduces incompatible API changes. 1.0.0a1: first alpha version. 1.0.0b1: first beta version. 1.0.0rc1: first release candidate. 1.0.0.dev1: first development build. 1.0.0.post1: first post‑release.

Conclusion

PEP 440 provides a clear, unified version‑numbering scheme that enhances maintainability, dependency resolution, and release stability for Python projects, making it essential knowledge for every Python developer.