Hugging Face released Transformers 5.24.0 on November 21, 2026, bringing upgrade work for teams maintaining custom model caches and PEFT adapters. For 5.24, make custom cache update methods accept the additional keyword input and use PEFT 0.22.0 or newer for adapter workflows. Old cache argument names remain temporarily supported, but that does not postpone these integration checks.
An inference cache stores intermediate calculations so a model can reuse earlier work while generating an answer. This migration concerns the code handling that state, not a folder of downloaded model files.
Treat this as two migration tracks: integration work for 5.24, followed by cleanup of old argument names. Start by identifying whether your application owns custom cache classes, model wrappers or adapter-loading code.
Make custom cache updates accept the new keyword
The released Llama attention code calls cache.update with kwargs=kwargs. An override accepting only key_states, value_states and layer_idx after self cannot accept that extra named argument unchanged.
Review both the outer cache class and any custom per-layer update methods. The base Cache implementation accepts *args and **kwargs and forwards them to the selected layer. An outer method that accepts the new keyword can still pass it to an incompatible layer.
Adapt the override to accept the keyword while preserving existing extra arguments and cache behavior. Forward metadata where the underlying implementation needs it. A permissive signature alone does not establish that your custom cache handles the information correctly.
Choose a compatible PEFT dependency
PEFT provides parameter-efficient fine-tuning methods, including adapters that customize a model without updating all its weights. Transformers 5.24 sets MIN_PEFT_VERSION to 0.22.0 in its released integration. PEFT 0.22.0 was released on November 19, so the required version is available.
Manage that dependency explicitly: PEFT is not in Transformers’ base installation requirements, so upgrading Transformers alone need not upgrade PEFT. Select a version at or above 0.22.0 that also satisfies your other libraries’ constraints. Plain Transformers use without adapters does not require installing PEFT for this change.
As checked on November 21, the versioned PEFT overview still states a 0.20.0 minimum. For this upgrade, use the 0.22.0 requirement in the released integration.
The PEFT compatibility change explains why accepting an old argument is not enough: adapter code also inspects model function signatures. A wrapper can accept an old name while exposing the new one to inspection. The fix updates both name selection and signature checks.
For adapters on compressed base models, Transformers FP8 adapter-training support covers the separate hardware and backend eligibility question. Updating PEFT does not by itself establish that a particular FP8 training setup qualifies.
Move old names to cache on the right schedule
The release notes consolidate past_key_values and cache_params into cache. For callers using legacy input names, the announced compatibility windows differ:
Where the old input name is used | Announced transition boundary | Recommended cleanup |
|---|---|---|
Model forward and prepare_inputs_for_generation | v5.40.0 | Change the input name to cache before adopting that version. |
generate | v6.0.0 | Change legacy cache arguments to cache before adopting that version. |
The tagged generation code carries these separate deprecation markers. They are software-version boundaries, not calendar deadlines; the cited announcement gives no release dates for those future versions. Do not use the longer generation window to defer custom model or cache changes needed for 5.24.
Update custom model signatures and wrappers deliberately. If your application must support older Transformers versions too, keep version-aware name handling at the integration boundary, as PEFT’s compatibility helpers do. Do not globally replace unrelated variable names or persisted data fields.
For results, prefer outputs.cache. The ModelOutput compatibility code preserves old attribute and key lookups, but the actual field uses the new name. Check code that enumerates output fields or serializes them: successful outputs.past_key_values access does not mean an exported dictionary still contains that key.
Pass only one cache spelling per call or output constructor. In particular, remove stale keys when merging argument dictionaries. Compatibility handling differs between argument decorators and output constructors, so do not rely on every mixed-name call producing the same error.
Check the application before production
Before changing the environment, retain the known-working dependency lock and record model and adapter revisions. In a separate environment, check the paths your application actually uses:
Ordinary generation and generation that reuses an existing cache, including your custom update methods.
Adapter loading and switching, plus any prefix-tuning or other signature-dependent workflow.
Custom model wrappers, argument-dictionary merging and output serialization.
Every Transformers version you claim to support, if the application spans both naming conventions.
If a required extension is not ready, retain the previously validated stack while resolving its compatibility. These are recommended checks, not evidence that every external model works. This guide covers cache and PEFT migration; consult the full 5.24 release notes for other breaking changes affecting your models.
The rename itself establishes no speed improvement or cost saving. If you are separately considering shared caching across inference servers, see when distributed KV caching pays for itself. That infrastructure purchase is not required for this interface migration.
