●Change8

Migrating to Transformers v5.0.0rc0

Version v5.0.0rc0 introduces 2 breaking changes. This guide details how to update your code.

Released: 12/1/2025

2
Breaking Changes
5
Migration Steps
11
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

WeightConverterWeightTransformConversionOpsConcatenateTokenizersBackendSentencePieceBackendPythonBackendMistralCommonBackendAutoTokenizerfrom_pretrainedgenerate_merges

Breaking Changes

●Issue #1

The API for loading and transforming model weights has been significantly overhauled, moving to a new system centered around the WeightConverter class.

✓Solution

Review the new dynamic weight loading API, specifically the use of the WeightConverter class, ConversionOps (like Concatenate), source_keys, and target_keys, to replace older, less flexible weight manipulation logic during model loading.

●Issue #2

Tokenizer definition has been simplified, introducing a new structure where tokenizers inherit from TokenizersBackend and manage the underlying tokenizers library object more directly.

✓Solution

If you were manually subclassing or initializing tokenizers in a way that predates this new structure, you must update your custom tokenizer definitions to align with the new TokenizersBackend inheritance and initialization pattern shown in the Llama5Tokenizer example.

Migration Steps

  1. 1
    Install the release candidate of Transformers v5 using pip install transformers --pre to begin testing.
  2. 2
    Thoroughly test all model loading procedures, especially those involving custom weight transformations, quantization, or parallelism setups, as the weight loading API has changed.
  3. 3
    If you have custom tokenizer implementations, refactor them to inherit from the new TokenizersBackend class and update their initialization logic according to the new standards.
  4. 4
    Review the documentation or blog post linked in the release notes for a deeper understanding of the WeightConverter and dynamic weight loading mechanisms.
  5. 5
    Provide feedback on any inconsistencies or bugs encountered during testing via the official GitHub issues tracker.

Release Summary

Transformers v5 introduces a major overhaul of the library, featuring a new dynamic weight loading API and a unified tokenizer backend system to simplify internals and improve performance.

Need More Details?

View the full release notes and all changes for Transformers v5.0.0rc0.

View Full Changelog