In practice, provisional APIs have been quite stable. The term "provisional" was introduced for PEPs that introduce new modules, where we wanted to allow some wiggle room for changes based on experience with using the new module during the first release cycle where it's made available. You can think of it as a sort of extended beta period for that module only. Generally provisional status only lasts for one release cycle.

"Unstable" has a different meaning -- it's for APIs (including modules) that are likely to change in every release (or most releases, anyway). Users are not discouraged from using these, but they *must* be mindful of their code breaking with every new release.

I could imagine some unstability to allow incompatible changes in bugfix releases, though for my main use case it would be sufficient to only allow those in minor releases.

On Thu, Jun 3, 2021 at 10:32 AM Senthil Kumaran <> wrote:
On Thu, Jun 03, 2021 at 10:10:53AM -0700, Guido van Rossum wrote:
> This is not a complete thought yet, but it occurred to me that while we have
> deprecated APIs (which will eventually go away), and provisional APIs (which
> must mature a little before they're declared stable), and stable APIs (which
> everyone can rely on), it might be good to also have something like *unstable*
> APIs, which will continually change without ever going away or stabilizing.

The first grey area will between Provisional API vs Unstable API.

Do developers consider provisional APIs as stable and start relying upon
heavily? I am not sure.

I also lack the experience for the use-cases that you are thinking


--Guido van Rossum (
Pronouns: he/him (why is my pronoun here?)