Use semantic versioning if your users need to judge upgrade risk from the number. Use calendar versioning if you release on a schedule and deprecate features over several releases. Both work with pip as long as the number follows the standard version format.
What each scheme means
Semantic versioning, or SemVer, uses major, minor and patch. The Python Packaging User Guide summarizes the rules: increment major for incompatible API changes, minor for backward compatible functionality, and patch for backward compatible bug fixes.
Calendar versioning, or CalVer, encodes a date, typically year and month. The guide's example is 23.12 for December 2023. It notes that pip itself uses calendar versioning.
| SemVer | CalVer | |
|---|---|---|
| Number says | How risky an upgrade is | How old the feature set is |
| Good for | APIs consumers build on | Tools with a regular release rhythm |
| Example | 2.4.1 | 26.10 |
| Weakness | Maintainers and users disagree on what counts as breaking | Says nothing about compatibility |
How to choose
- Do other libraries depend on yours? If yes, SemVer helps them write sensible ranges.
- Do you ship on a fixed calendar with deprecation warnings first? The guide says SemVer is not a suitable choice for projects with a regular time based release cadence and a deprecation process that warns for several releases before removal. CalVer fits.
- Are you a command line tool? Users rarely write ranges against it, so either works.
- Do you prefer a simple serial number? The guide calls this easiest to manage and hardest for users to track, since it says nothing about compatibility.
A reality check on SemVer
The guide is candid. Version bumps reflect the maintainer's view, which may differ from the user's perception of what the scheme promises. Most large projects do not follow strict SemVer, since many changes are technically breaking but affect few users. The guide cites a scientific library that uses loose SemVer, where minor releases can contain backward incompatible changes.
The guide adds a point that matters for security. Maintainers may knowingly break the assumption that the last segment is backward compatible, for example when a security vulnerability must be addressed. Security releases often arrive as patch versions that still contain breaking changes.
How consumers use the scheme
If you use strict SemVer, consumers can use the compatible release operator. The guide says name ~= X.Y roughly means at least X.Y with the same X, and name ~= X.Y.Z allows later patch releases with the same X and Y. Details are in our post on compatible release versus exact match.
Switching schemes later
Changing from CalVer to SemVer can make new numbers look older than old ones. The guide describes epochs as a way to fix sorting, but discourages them, and suggests picking a higher version number unlikely to confuse users, such as 100.0.
Whatever you pick
- Follow the standard version format so pip can sort your releases.
- Document your policy in the README, including how you treat security releases.
- Be consistent. A scheme only helps if users can predict it.
Try it yourself
Click through it at your own pace, or open it full screen.
Look at how a fixed version is presented and think about what your own version number would tell a consumer in the same screen.
Safeguard's dependency scanning shows fixed versions for findings. A free scan is a place to see them.
Quick check
Does pip care which scheme I use?
No, as long as the version follows the standard format. The scheme matters to humans and to range writing.
Can a patch release contain breaking changes?
The guide says it can, for example when a security fix requires it. Say so clearly in release notes.
What is an epoch?
A prefix such as 1! that fixes sorting after a scheme change. The guide discourages it and suggests a higher number instead.
Sources
Last reviewed: 19 October 2026.
