V5 migration

The largest breaking release in the library's history. The changes are documented exhaustively in MIGRATION_GUIDE_V5.md (in the repo root, ~800 lines). This page is a guided tour rather than a substitute.

Headline changes

TensorFlow and Flax removed (PR #40760)

V5 ships PyTorch only. Every TF* and Flax* class has been removed from the public API. Reasons:

• Maintenance cost per architecture × three backends became unsustainable as model count grew.
• The vast majority of users had moved to PyTorch.
• Cooperating with JAX tools (MaxText, etc.) is the path forward, not maintaining a parallel implementation.

If you previously relied on TF/Flax, the v4 series is still available on PyPI and the Hub.

New weight-loading API (PR #41580)

The WeightConverter abstraction replaces ad-hoc state-dict munging:

class WeightConverter(WeightTransform):
    operations: list[ConversionOps]
    source_keys: Union[str, list[str]]
    target_keys: Union[str, list[str]]

Operations include Concatenate, Transpose, MergeModulelist, WeightRenaming, etc. (see src/transformers/core_model_loading.py). The benefits:

• Reversible: save_pretrained after from_pretrained reproduces the input checkpoint.
• Composable with quantization, tensor parallelism, and MoE sharding.
• Faster loading via scheduled tensor materialization.

This is the underlying machinery for from_pretrained.

Tokenizer rewrite

Tokenizer definition simplified. The TokenizersBackend base class lets you instantiate an empty tokenizer and train it on a corpus:

class Llama5Tokenizer(TokenizersBackend):
    def __init__(self, unk_token="<unk>", bos_token="<s>", eos_token="</s>", vocab=None, merges=None):
        ...

mistral-common is now a first-class backend (src/transformers/tokenization_mistral_common.py).

CLI migrated to Typer (PR #41487, 2025-10-16)

The CLI was rewritten with Typer. Behavioural impacts:

• Help text is auto-generated from type hints and docstrings.
• New per-command modules under src/transformers/cli/.
• The entry script src/transformers/cli/transformers.py is now ~40 lines.

Continuous batching shipped (PR #40426, 2025-08)

src/transformers/generation/continuous_batching/ plus paged-attention kernels (src/transformers/integrations/*_paged.py) provide the production-grade serving path used by transformers serve --continuous-batching. See Continuous batching.

Renamed: PretrainedConfig → PreTrainedConfig

Both names work — the alias preserves backward compatibility. New code should use PreTrainedConfig.

Renamed: torch_dtype → dtype

from_pretrained(..., dtype=torch.bfloat16) is the new spelling. torch_dtype continues to work for backward compatibility.

Subtle but important breaks

transformers.Trainer moved off TF/Flax

TFTrainer and FlaxTrainer are gone. The single Trainer class is now PyTorch-only.

Model output dataclasses for TF/Flax removed

TF*Output, Flax*Output classes are gone. Migrate to the PyTorch dataclasses in src/transformers/modeling_outputs.py.

Some research models pruned

Models that had only TF/Flax implementations were dropped or moved under src/transformers/models/deprecated/.

Stricter docstring checks

utils/check_docstrings.py is more aggressive in v5; many models now use @auto_docstring and the validator enforces it. Run make fix-repo to apply auto-fixes.

Default attention is SDPA

Models default to attn_implementation="sdpa" on PyTorch 2+. Override with from_pretrained(..., attn_implementation="eager") if a model misbehaves with SDPA.

report_to="all" removal

TrainingArguments.report_to no longer accepts "all". Pass an explicit list (or ["none"]).

How to migrate

1. Pin and upgrade. Pin transformers==5.x and accelerate>=1.1.0, huggingface-hub>=1.5.0,<2.0, torch>=2.4.
2. Replace TF/Flax imports. Search the codebase for TF/Flax prefixes and rewrite using PyTorch equivalents.
3. Rename torch_dtype. Search-and-replace in calls to from_pretrained.
4. Re-run make fix-repo if you maintain a fork or downstream model.
5. Test. pytest tests/... for whatever subset matters to you.
6. Read the long-form migration guide. The version in the repo (MIGRATION_GUIDE_V5.md) covers many edge cases not summarized here, especially around tokenizer behaviour and Trainer flag renames.

See also

• MIGRATION_GUIDE_V5.md — the canonical long-form guide.
• from_pretrained — the new weight-loading API.
• Tokenization — the rewritten backend.
• CLI — the Typer migration.
• Continuous batching — new serving path.