litellm - 💡(How to fix) Fix [Feature]: Consistent versioning across PyPI and GitHub [1 participants]

Check for existing issues

• I have searched the existing issues and checked that my issue is not a duplicate.

The Feature

Align PyPI releases with the documented release cycle so that pip install litellm installs a stable, QA-tested version — not a nightly/dev build — and adopt a consistent, PEP 440-compliant versioning scheme across PyPI, GitHub tags, and Docker images.

Concretely, this means:

1. Use PEP 440 pre-release segments properly on PyPI: publish nightlies as 1.x.x.devN, release candidates as 1.x.xrcN, and only the stable build as the bare 1.x.x. This way pip install litellm automatically resolves to the stable version, while pip install litellm --pre gets the nightly. Alternatively, only publish -stable builds to PyPI.

2. Adopt a consistent GitHub tag format: pick one prefix convention (v or no v), one separator convention (- for stability suffixes, . for patch numbers), and stop mixing -, ., and _ in the same tag. Keep feature-branch builds out of the main release tag namespace.

3. Expose a stability indicator (e.g., litellm.__release_stage__ = "stable" | "rc" | "nightly") so programmatic consumers can verify what they're running.

4. Document the mapping between PyPI versions and GitHub release stages in the PyPI package description and README.

Motivation, pitch

We deploy LiteLLM as a proxy in production and have been bitten multiple times by the fact that PyPI versions do not correspond to what is considered "stable" by the releases on GitHub. The current situation makes it impossible for PyPI consumers to deploy with confidence in what they're actually running.

The problem in practice

LiteLLM documents a clear release cycle at https://docs.litellm.ai/docs/proxy/release_cycle:

• v1.x.x-nightly — passes CI/CD only
• v1.x.x.rc — passes CI/CD + manual review
• v1.x.x-stable — passes CI/CD + manual review + 3 days of production testing

But the version published to PyPI is always the nightly build. Right now:

So pip install litellm gives you a build two minor versions ahead of what is recommend for production. There is zero indication of this on PyPI.

The versioning chaos makes cross-referencing impossible

Even when we try to manually cross-reference PyPI versions with GitHub to understand what we're deploying, the tag namespace is impenetrable. Here is a sample of coexisting tags/releases:

v1.82.1-nightly                        ← nightly, v prefix, hyphen separator
1.82.1                                 ← the PyPI version (is that really what is deployed there though?), no v prefix, no suffix
1.82.1-dev-2                           ← dev build, no v prefix, hyphen separator
v1.82.0.patch2                         ← patch, v prefix, dot separator
v1.82.rc.3                             ← RC, v prefix, dot separator
v1.81.14-stable                        ← stable, v prefix, hyphen separator
v1.81.14-stable.gpt-5.4_patch2         ← hyphen AND dot AND underscore in one tag
v1.81.14-stable.gpt-5.4-patch7         ← same concept, but hyphen instead of underscore
v1.81.14.gemini-batches                ← feature-branch release in main tag space
v1.81.12-stable_gpt-5.3               ← underscore separator
1.81.12-stable.3                       ← no v prefix, dot separator
v1.81.6.rc.9                           ← RC, dot separator (not hyphen like others)
v1.80.5.dev1                           ← dev, dot separator
litellm-trace-dev-v1.81.16            ← completely different naming scheme

The problems compound:

• v prefix vs none: v1.82.1-nightly vs 1.82.1. No pattern.
• Separator roulette: -stable, .rc.3, _gpt-5.3, -stable.gpt-5.4_patch2 — sometimes all three separators in one tag.
• Feature branches in release tags: gemini-batches, gpt-5.4-patch7, redirect-alpha, litellm-trace-dev-v1.81.16 — these are cherry-picked feature builds, not documented in the release cycle, indistinguishable from real stable patches.
• PyPI has unexplained gaps: 1.80.13 → 1.80.15 (no .14), 1.81.1 → 1.81.3 (no .2), 1.80.0 → 1.80.5 (no .1–.4).
• Sporadic PyPI pre-release suffixes: Some versions have .dev prereleases (1.79.0.dev1), some have .post releases (1.75.5.post1), most have neither. No pattern or documentation.

Concrete difficulties this causes

1. Cannot pin to stable on PyPI. The -stable versions are never published there. The number 1.81.14 exists on PyPI, but it was published as a nightly at the time — the stable designation came later and was never reflected on PyPI.

2. Dependabot/Renovate always suggest nightly upgrades. Since stable releases don't exist as distinct PyPI versions, automated dependency tools will always propose upgrading to the latest nightly. There's no way to configure them to track only stable.

3. The PyPI page itself says "Use docker images with the -stable tag" — implicitly telling pip users that what they just installed is not the stable version, without offering an alternative for the Python SDK.

4. Lock files and pinning are unreliable. Pinning litellm==1.81.14 pins to the nightly build from that version. If issues were found and fixed in v1.81.14-stable.gpt-5.4-patch7, those patches are not available on PyPI.

What a fix would look like (PEP 440)

Using PEP 440 properly would solve this without breaking anything:

Users who want nightly can opt in with pip install litellm --pre. Everyone else gets the tested, stable build. This is how the Python ecosystem is designed to work.

What part of LiteLLM is this about?

SDK (litellm Python package)

LiteLLM is hiring a founding backend engineer, are you interested in joining us and shipping to all our users?

No

Twitter / LinkedIn details

No response