Use a post release, such as 1.2.0.post1, only for mistakes that do not affect the distributed software, like a typo in the release notes. For any real bug fix, publish a new patch version such as 1.2.1. The version specifiers spec strongly discourages post releases for maintenance fixes.
Definitions
A post release adds a .postN segment to a final version, as in 1.2.0.post1. It sorts immediately after 1.2.0 and ahead of any later release. A patch release increments the last number, as in 1.2.1.
What the specification says
The version specifiers specification describes post releases as a way to address minor errors in a final release that do not affect the distributed software, with the example of correcting an error in the release notes. It adds that using post releases to publish maintenance releases containing actual bug fixes is strongly discouraged. It is better to use a longer release number and increment the final component for each maintenance release.
The Packaging User Guide repeats this in its versioning discussion: post releases should not be used for bug fixes, which belong in a new final release.
Which to choose
| Situation | Use |
|---|---|
| Typo in the release notes | Post release is acceptable |
| Wrong text in the README shown on PyPI | Post release is acceptable |
| Missing file in the wheel that breaks imports | New patch version |
| Bug fix in code | New patch version |
| Security fix | New patch version, clearly announced |
The question to ask is whether the installed software changed. If yes, you need a version that signals a change.
Why patch versions are better for fixes
- Security tooling reads versions. Advisories describe affected and fixed versions. A clear fixed version such as 1.2.1 makes matching simple. A post release is harder for people and tools to reason about.
- Humans read versions. Users scanning a changelog understand 1.2.1 instantly.
- Ordering is predictable. Post releases sort between the final release and the next one, which is correct but easy to misread.
The wheel specification adds a related warning about build numbers. Build numbers are not part of the version, and the spec says that when a rebuilt distribution must be referenced externally, for example to resolve a security vulnerability, a new version should be created instead.
You cannot overwrite a bad upload
If you published a broken file, you cannot reuse its name. The PyPI help page says a distribution filename cannot be reused, even after deletion. So the fix is always a new version number. For a related topic, see can you overwrite a published package version.
What to do after a bad release
- Fix the problem and run the checks from our sdist checklist.
- Choose a patch version for code or packaging fixes. Choose a post release only for metadata level notes.
- Consider yanking the bad release if it is broken or vulnerable. Yanking marks it so installers skip it unless pinned exactly, and PyPI encourages giving a reason.
- Write a short changelog entry.
Safeguard's SBOM and dependency scanning record exact versions, so a clean patch number makes it easy to see who has the fix. A free scan shows versions across a project.
Quick check
Does 1.2.0.post1 sort before or after 1.2.0?
After. A post release sorts immediately after the matching final release and before any later release.
Can I fix a bug with a post release?
You can, but the specification strongly discourages it. Use a new patch version instead.
Can I replace a broken file under the same version?
No. PyPI does not allow a filename to be reused. Publish a new version.
Sources
- Version specifiers, Python Packaging User Guide
- Versioning, Python Packaging User Guide
- Binary distribution format, Python Packaging User Guide
- PyPI help, FAQ
- Yanking, PyPI Docs
Last reviewed: 19 October 2026.
