fix(packaging): support Python 3.14

[Technolog796]

Relevant issues

Fixes #26343

Linear ticket

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all CI/CD checks that can run from this fork; Block fork dependency changes is expected because this PR updates uv.lock
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review; re-requested after the latest rebase

Local note: make test-unit previously stopped on tests/test_litellm/proxy/test_proxy_server.py::test_login_v3_exchange_happy_path because the existing _FakeRedisCache test double is missing _circuit_breaker. This is unrelated to the Python 3.14 packaging changes in this PR

Delays in PR merge?

N/A

Screenshots / Proof of Fix

Before this change, at base commit 3e9e52042a, pyproject.toml blocks Python 3.14 with requires-python = ">=3.10, <3.14". The same base uses the restored maturin backend with pyo3 0.23.5, which fails on Python 3.14 because PyO3 0.23 only supports up to Python 3.13

After this change, at commit 7dc863a86b:

uv lock --check
Resolved 418 packages in 5ms

uv sync --frozen --python 3.14 --all-groups --all-extras
Built litellm-enterprise @ file:///Users/ilakulesov/Documents/python_projects/litellm/enterprise
Built litellm @ file:///Users/ilakulesov/Documents/python_projects/litellm

uv run --no-sync python - <<'PY'
import litellm
import fastuuid
import redisvl
import semantic_router
import aurelio_sdk
import pypdf
import openapi_core
import ddtrace
print("import smoke ok")
PY
import smoke ok

uv run --no-sync pytest tests/test_litellm/test_uuid_helper.py tests/test_litellm/caching/test_s3_cache.py --tb=short -q
19 passed in 1.00s

cd litellm-rust
cargo fmt --check
cargo clippy -p litellm-ai-gateway --all-targets --features server -- -D warnings
cargo clippy -p litellm-core -p litellm-python-bridge --all-targets -- -D warnings
cargo clippy -p litellm-ai-gateway --all-targets --features python-config -- -D warnings
cargo test -p litellm-python-bridge

make pre-commit
./scripts/pre_commit_lint.sh

Type

Bug Fix
Infrastructure
Test

Changes

This PR expands the supported Python range to include Python 3.14 while preserving the existing Python 3.10 through 3.13 support window. It removes stale <3.14 dependency markers for packages that now install and import on Python 3.14, keeps ddtrace on the existing 2.x range for Python <3.14, and uses the Python 3.14-compatible 3.x range only on Python 3.14+

The lockfile was regenerated so Python 3.14 resolution is represented explicitly. The installer comments were updated so Python 3.14 is no longer described as too new. The S3 cache async tests now assert unordered call multisets instead of relying on async call ordering. A targeted Python 3.14 workflow checks lockfile validity, frozen installation, import smoke for litellm, fastuuid, and the previously gated optional dependencies, Datadog tracing wrapper smoke for the ddtrace 3.x path, plus the UUID and S3 cache regression tests

The current staging base uses the maturin backend for the Rust bridge, so this PR also updates the Rust bridge to pyo3 0.29.0 / pyo3-async-runtimes 0.29.0 and the matching PyO3 API names. Without that, Python 3.14 wheel builds fail before LiteLLM can install

[CLAassistant]

All committers have signed the CLA.

[Technolog796]

@greptileai

[greptile-apps]

Greptile Summary

This PR adds Python 3.14 support by extending requires-python to <3.15, removing stale python_version < '3.14' environment markers, splitting ddtrace into a 2.x (Python <3.14) and 3.x (Python ≥3.14) range, and upgrading the Rust bridge from PyO3 0.23 to 0.29 (the minimum required for Python 3.14 wheel builds). A dedicated CI workflow validates lockfile correctness, frozen installation, import smoke tests, ddtrace 3.x API smoke, and the UUID/S3 cache regression suite under Python 3.14.

• pyproject.toml: requires-python widened to <3.15; markers dropped for redisvl, semantic-router, aurelio-sdk, pypdf, and openapi-core; ddtrace split into two version ranges by Python version.
• Rust bridge (Cargo.toml, config.rs, gil.rs, lib.rs): PyO3 bumped from 0.23.5 → 0.29.0 with matching API rename (Python::with_gil → Python::attach, py.allow_threads → py.detach).
• test_s3_cache.py: Async call-order assertions replaced with Counter-based multiset comparisons, making tests stable under Python 3.14's different async task scheduling order without losing coverage.

Confidence Score: 5/5

Safe to merge — changes are narrowly scoped to packaging metadata, PyO3 API renames, and async test ordering; no production logic is altered

The Python version gate change, dependency marker removals, and PyO3 rename are all mechanical and well-tested locally plus via the new CI workflow. The test assertion changes faithfully preserve the same behavioral contracts with order-independent comparisons. No runtime logic in the Python layer is touched.

No files require special attention beyond the minor stale doc comment in litellm-rust/crates/python-bridge/src/gil.rs

Important Files Changed

Filename	Overview
pyproject.toml	Extends requires-python to <3.15, removes stale python_version < '3.14' markers for redisvl/semantic-router/aurelio-sdk/pypdf/openapi-core, and version-splits ddtrace into 2.x (Python <3.14) and 3.x (Python ≥3.14)
litellm-rust/Cargo.toml	Bumps pyo3 from 0.23.5 to 0.29.0 and pyo3-async-runtimes from 0.23.0 to 0.29.0 to support Python 3.14 wheel builds
litellm-rust/crates/python-bridge/src/gil.rs	Updates GIL release wrapper from py.allow_threads to py.detach for PyO3 0.29, but the module-level doc comment still references the old Python::allow_threads name
litellm-rust/crates/ai-gateway/src/python/config.rs	Replaces Python::with_gil with Python::attach for PyO3 0.29 compatibility in the config loader
litellm-rust/crates/python-bridge/src/lib.rs	Replaces Python::with_gil with Python::attach for PyO3 0.29 compatibility in the async OCR result handler
.github/workflows/test-python-314.yml	New CI workflow that checks the lockfile, installs with Python 3.14, runs import smoke tests for key optional packages, exercises the ddtrace 3.x wrapper, and runs the UUID/S3 cache regression tests
tests/test_litellm/caching/test_s3_cache.py	Changes order-dependent call assertions to Counter-based multiset comparisons to accommodate Python 3.14's different async task scheduling order; coverage is preserved
scripts/install.sh	Removes the 3.14+ example from the comment describing unsupported Python version ranges
scripts/install-cli.sh	Removes the 3.14+ example from the comment describing unsupported Python version ranges

_{Reviews (9): Last reviewed commit: "fix(packaging): support python 3.14 rust..." | Re-trigger Greptile}

[greptile-apps]

Greptile Summary

This PR extends litellm's supported Python range to include 3.14 by bumping requires-python to <3.15, removing stale python_version < '3.14' markers from packages that now install cleanly on 3.14, splitting ddtrace into a 2.x range for older Pythons and a 3.x range for 3.14+, and adding a targeted CI workflow to verify the new support window.

• pyproject.toml: redisvl, semantic-router, aurelio-sdk, pypdf, and openapi-core lose their < '3.14' guards; ddtrace gets a versioned split (>=2.19.0,<3.0 for < '3.14', >=3.19.7,<4.0 for >= '3.14').
• .github/workflows/test-python-314.yml: New workflow with SHA-pinned actions runs lockfile check, frozen install, import smoke, and the S3 cache + UUID regression tests against Python 3.14.
• tests/test_litellm/caching/test_s3_cache.py: Positional-order assertions on put_object mock calls replaced with key-based dict lookups to handle async non-determinism on 3.14; coverage is effectively equivalent given the call_count guards already in place.

Confidence Score: 4/5

Safe to merge — changes are isolated to packaging metadata, installer comments, the lockfile, and two async test assertions.

The packaging and workflow changes are clean and well-scoped. The only non-trivial code change is in the S3 cache tests, where the new dict-comprehension approach silently drops duplicate-key mock calls; the existing call_count assertions prevent false positives today, but the pattern is slightly less defensive than a multi-value map would be.

tests/test_litellm/caching/test_s3_cache.py — review the dict-based assertion approach for the async put_object calls.

Important Files Changed

Filename	Overview
.github/workflows/test-python-314.yml	New CI workflow for Python 3.14 — checks lockfile validity, frozen install, import smoke, and regression tests. Actions are SHA-pinned; uv version is pinned. Workflow fires only on pull_request, not on direct pushes to target branches (common pattern, not a defect).
pyproject.toml	Extends requires-python upper bound to <3.15, removes python_version < '3.14' guards from redisvl/semantic-router/aurelio-sdk/pypdf/openapi-core (all now install on 3.14), and splits ddtrace into 2.x (< 3.14) and 3.x (>= 3.14) markers. Changes are consistent and well-scoped.
tests/test_litellm/caching/test_s3_cache.py	Replaced positional-order assertions with key-based dict lookups to handle async call-ordering non-determinism under Python 3.14. Assertion equivalence holds for current tests (call_count guards prevent over/under-call regressions), but the dict comprehension drops duplicate-key calls silently.
scripts/install-cli.sh	Comment-only update: removes the stale "too-new (3.14+)" wording now that 3.14 is supported.
scripts/install.sh	Same comment-only update as install-cli.sh — no behavioural change.
uv.lock	Auto-generated lockfile regenerated to include Python 3.14 resolution. No manual edits expected or required.

_{Reviews (2): Last reviewed commit: "fix(packaging): support python 3.14" | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Sameerlite]

Thanks for the PR! A couple of things to get this over the finish line:

• The CI checks are currently failing — could you take a look? If any failures are pre-existing or unrelated to your change, a quick note in a comment helps us move faster.

Once those are addressed we'll take another look — appreciate the contribution!

[Technolog796]

@Sameerlite Thanks, I checked the failing checks

The Python 3.14 check added in this PR is passing, as are lint and Codecov

The remaining failures look unrelated:

• auth-checks / Run tests was cancelled before pytest started while downloading uv
• logging-misc / Run tests and proxy-runtime / Run tests were cancelled before pytest started while running prisma generate / Installing Prisma CLI
• Block fork dependency changes fails because this is a fork PR changing uv.lock, which is required for the Python 3.14 lockfile update
• osv-scan reports existing dependency advisories in uv.lock and the dashboard package-lock.json; fixing those would be a separate security PR

So I don’t see a code/test failure caused by this PR

[Technolog796]

Rebased on latest litellm_internal_staging after #30815 and regenerated uv.lock with the new boto3 stubs preserved.

Local verification passed:

• uv lock --check
• uv sync --frozen --python 3.14 --all-groups --all-extras
• import smoke for litellm, fastuuid, redisvl, semantic_router, aurelio_sdk, pypdf, openapi_core
• targeted pytest for UUID helper + S3 cache tests: 19 passed

Current non-code failures:

• Block fork dependency changes: expected for this fork PR because Python 3.14 support requires uv.lock changes.
• osv-scan: pre-existing lockfile/dashboard dependency findings on the current base; chore(typing): add boto3/botocore stubs so basedpyright resolves the AWS SDK #30815 showed the same OSV failure

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 1 · PR risk: 0/10

[Sameerlite]

Thanks for rebasing and keeping this up to date, @Technolog796! The CI explanation (Block fork dependency changes is expected for a fork PR touching uv.lock; osv-scan failures are pre-existing) makes sense. Triggering a fresh Greptile review against the latest head.\n\n@greptileai

[Technolog796]

@greptileai

[Technolog796]

@greptileai

[Technolog796]

@Sameerlite I pushed one more rebase on top of the latest litellm_internal_staging. The only remaining red check is still the expected Block fork dependency changes, since this fork PR updates uv.lock. I also retriggered Greptile on the latest head: 9ea8d62075

[Technolog796]

@greptileai

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[Technolog796]

@greptileai

[Technolog796]

@Sameerlite Hi! Is there any news about my PR?

[Technolog796]

@greptileai

[kantorcodes]

Hi! It'd be great to support Python 3.14. Is there any update on this?

[Technolog796]

@greptileai

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing Technolog796:litellm_python_314_support (7dc863a) with litellm_internal_staging (3e9e520)}

[Technolog796]

@Sameerlite Hi! Is there any news about my PR?

[yudelevi]

@Technolog796 heads-up I opened #33264 before finding this PR, apologies for the overlap. Mine is a strict subset of yours (just the pyo3 0.29 bump + rename migration, against litellm_oss_staging, currently mergeable). Left a note there deferring to maintainers on which vehicle to merge