transformers breaking changes

5.9.0

62 breaking changes, first published May 20, 2026.

• Removed
  OpenTelemetry integration was removed from the continuous batching (CB) feature. Code that relies on it will no longer get that telemetry. github.com
• Removed masking_utils.py
  The mask visualization tool was removed from masking_utils.py. Code that calls it must be changed. github.com
• Behavior changed
  Repetition penalty now requires input_ids to be passed. Callers that omit it must now provide it. github.com
• Behavior changed text_embeds
  The text_embeds input for these models now takes full text embeddings instead of pooler outputs. Users must update their inputs to match. github.com
• Signature changed transformers.cli.serve.Serve.__init__
  Was def __init__(self, force_model: Annotated[str | None, typer.Argument(help='Model to preload and use for all requests.')] = None, continuous_batching: Annotated[bool, typer.Option(help='Enable continuous batching with paged attention... pypi.org
• Signature changed transformers.cli.serving.chat_completion.BaseGenerateManager.generate_streaming
  Was def generate_streaming(self, model: PreTrainedModel, processor: ProcessorMixin | PreTrainedTokenizerFast, inputs: dict, gen_config: GenerationConfig, request_id: str, tool_config: dict | None = None) -> tuple[asyncio.Queue... pypi.org
• Signature changed transformers.cli.serving.chat_completion.BaseHandler.__init__
  Was def __init__(self, model_manager: ModelManager, generation_state: GenerationState); now def __init__(self, model_manager: ModelManager, generation_state: GenerationState, chat_template_kwargs: dict | None = None). pypi.org
• Signature changed transformers.cli.serving.transcription.DirectStreamer.__init__
  Was def __init__(self, tokenizer: tokenizers.Tokenizer, loop: asyncio.AbstractEventLoop, queue: asyncio.Queue, skip_special_tokens: bool = True, tool_config: dict | None = None); now def __init__(self, tokenizer: tokenizers.Tokenizer... pypi.org
• Signature changed transformers.cli.serving.transcription.GenerateManager.generate_streaming
  Was def generate_streaming(self, model: PreTrainedModel, processor: ProcessorMixin | PreTrainedTokenizerFast, inputs: dict, gen_config: GenerationConfig, request_id: str, tool_config: dict | None = None) -> tuple[asyncio.Queue... pypi.org
• Signature changed transformers.cli.serving.utils.CBGenerateManager.generate_streaming
  Was def generate_streaming(self, model: PreTrainedModel, processor: ProcessorMixin | PreTrainedTokenizerFast, inputs: dict, gen_config: GenerationConfig, request_id: str, tool_config: dict | None = None) -> tuple[asyncio.Queue... pypi.org

And 52 more in this version.

5.8.0

11 breaking changes, first published May 5, 2026.

• Removed
  Apex integration, including RMSNorm usage in T5 and related models, has been removed. Users relying on Apex for mixed precision or fused ops should migrate to PyTorch's native equivalents. github.com
• Signature changed transformers.cache_utils.DynamicSlidingWindowLayer.__init__
  Was def __init__(self, sliding_window: int); now def __init__(self, config: PreTrainedConfig | None = None, sliding_window: int | None = None). pypi.org
• Signature changed transformers.cli.serving.build_server
  Was def build_server(model_manager: ModelManager, chat_handler: ChatCompletionHandler, completion_handler: CompletionHandler, response_handler: ResponseHandler, transcription_handler: TranscriptionHandler, enable_cors: bool = False) ->... pypi.org
• Signature changed transformers.ContinuousBatchingConfig.__init__
  Was def __init__(self, block_size: int = 256, num_blocks: int | None = None, max_batch_tokens: int | None = None, max_memory_percent: float | None = None, max_blocks_per_request: int | None = 0, allow_block_sharing: bool = True... pypi.org
• Signature changed transformers.ContinuousMixin.continuous_batching_context_manager
  Was def continuous_batching_context_manager(self, generation_config: GenerationConfig | None = None, block: bool = True, timeout: float | None = None, continuous_batching_config: ContinuousBatchingConfig | None = None, persistent_manager... pypi.org
• Signature changed transformers.ContinuousMixin.init_continuous_batching
  Was def init_continuous_batching(self, generation_config: GenerationConfig | None = None, continuous_batching_config: ContinuousBatchingConfig | None = None, **deprecated_kwargs) -> ContinuousBatchingManager; now def... pypi.org
• Signature changed transformers.DynamicLayer.__init__
  Was def __init__(self); now def __init__(self, config: PreTrainedConfig | None = None). pypi.org
• Signature changed transformers.generation.CandidateGenerator.get_candidates
  Was def get_candidates(self, input_ids: torch.LongTensor) -> tuple[torch.LongTensor, torch.FloatTensor]; now def get_candidates(self, input_ids: torch.LongTensor, **kwargs) -> tuple[torch.LongTensor, torch.FloatTensor]. pypi.org
• Signature changed transformers.integrations.finegrained_fp8.Fp8Dequantize.convert
  Was def convert(self, input_dict: dict[str, torch.Tensor], full_layer_name: str | None = None, **kwargs) -> dict[str, torch.Tensor]; now def convert(self, input_dict: dict[str, list[torch.Tensor] | torch.Tensor], full_layer_name: str |... pypi.org
• Signature changed transformers.masking_utils.create_bidirectional_sliding_window_mask
  Was def create_bidirectional_sliding_window_mask(config: PreTrainedConfig, inputs_embeds: torch.Tensor, attention_mask: torch.Tensor | None, past_key_values: Cache | None = None, or_mask_function: Callable | None = None, and_mask_function... pypi.org

And 1 more in this version.

5.7.0

24 breaking changes, first published April 28, 2026.

• Behavior changed
  Configurations with problem_type set to single_label_classification and num_labels=1 now raise a clear error instead of proceeding. github.com
• Behavior changed PreTrainedTokenizerFast
  Decoding with BPE tokenizers in PreTrainedTokenizerFast now skips clean_up_tokenization, so decoded text can differ from earlier versions. github.com
• Signature changed transformers.ContinuousBatchingConfig.__init__
  Was def __init__(self, block_size: int = 256, num_blocks: int | None = None, max_batch_tokens: int | None = None, max_memory_percent: float = 0.8, max_blocks_per_request: int | None = 0, allow_block_sharing: bool = True... pypi.org
• Signature changed transformers.ContinuousBatchingConfig.max_memory_percent
  Was max_memory_percent: float; now max_memory_percent: float | None. pypi.org
• Signature changed transformers.ContinuousBatchingManager.warmup
  Was def warmup(self, num_query_tokens: int = 0, num_cache_tokens: int = 0) -> None; now def warmup(self) -> None. pypi.org
• Signature changed transformers.ContinuousMixin.continuous_batching_context_manager
  Was def continuous_batching_context_manager(self, generation_config: GenerationConfig | None = None, block: bool = True, timeout: float | None = None, continuous_batching_config: ContinuousBatchingConfig | None = None, persistent_manager... pypi.org
• Signature changed transformers.core_model_loading.LoadStateDictConfig.__init__
  Was def __init__(self, pretrained_model_name_or_path: str | None = None, download_kwargs: DownloadKwargs | None = DownloadKwargs(), use_safetensors: bool | None = None, ignore_mismatched_sizes: bool = False, sharded_metadata: dict | None =... pypi.org
• Signature changed transformers.core_model_loading.LoadStateDictConfig.device_mesh
  Was device_mesh: Optional[torch.distributed.device_mesh.DeviceMesh]; now device_mesh: DeviceMeshLike | None. pypi.org
• Signature changed transformers.generation.continuous_batching.cache.PagedAttentionMemoryHandler.__init__
  Was def __init__(self, block_size: int, page_size: int, num_groups: int, group_size: int, peak_activation_per_token: int, num_attention_masks: int, continuous_batching_config: ContinuousBatchingConfig) -> None; now def __init__(self... pypi.org
• Signature changed transformers.generation.continuous_batching.cache.PagedAttentionMemoryHandler.infer_num_blocks_and_max_batch_tokens
  Was def infer_num_blocks_and_max_batch_tokens(self, num_blocks: int | None = None, max_batch_tokens: int | None = None, max_memory_percent: float = 0.8, cache_dtype: torch.dtype = torch.float16) -> tuple[int, int]; now def... pypi.org

And 14 more in this version.

5.6.0

74 breaking changes, first published April 22, 2026.

• Removed rotary_fn
  Code that calls self.rotary_fn(...) inside an Attention module will break and must call the function directly instead. github.com
• Signature changed transformers.audio_utils.load_audio_torchcodec
  Was def load_audio_torchcodec(audio: str | np.ndarray, sampling_rate=16000) -> np.ndarray; now def load_audio_torchcodec(audio: str | np.ndarray, sampling_rate=16000, timeout=None) -> np.ndarray. pypi.org
• Signature changed transformers.BatchEncoding
  Was class BatchEncoding(UserDict); now class BatchEncoding(UserDict, Generic[_V]). pypi.org
• Signature changed transformers.BatchEncoding.__getitem__
  Was def __getitem__(self, item: int | str) -> Any | EncodingFast; now def __getitem__(self, item: int | str | slice) -> _V | EncodingFast | dict[str, _V]. pypi.org
• Signature changed transformers.BatchEncoding.to
  Was def to(self, device: str | torch.device, *, non_blocking: bool = False) -> BatchEncoding; now def to(self, device: str | torch.device, *, non_blocking: bool = False) -> BatchEncoding[torch.Tensor]. pypi.org
• Signature changed transformers.cli.add_new_model_like.find_modular_structure
  Was def find_modular_structure(module_name: str, old_model_infos: ModelInfos, new_cased_name: str) -> tuple[str, str, list]; now def find_modular_structure(module_name: Path, old_model_infos: ModelInfos, new_cased_name: str) -> tuple[str... pypi.org
• Signature changed transformers.cli.chat.RichInterface.stream_output
  Was async def stream_output(self, stream: AsyncIterator[ChatCompletionStreamOutput]) -> tuple[str, str | Any | None]; now async def stream_output(self, stream: Awaitable[AsyncIterator[ChatCompletionStreamOutput]]) -> tuple[str, str | Any |... pypi.org
• Signature changed transformers.cli.serving.build_server
  Was def build_server(model_manager: ModelManager, chat_handler: ChatCompletionHandler, response_handler: ResponseHandler, transcription_handler: TranscriptionHandler, enable_cors: bool = False) -> FastAPI; now def... pypi.org
• Signature changed transformers.cli.serving.chat_completion.BaseGenerateManager.generate_non_streaming
  Was def generate_non_streaming(self, model: PreTrainedModel, processor: ProcessorMixin | PreTrainedTokenizerFast, inputs: dict, gen_config: GenerationConfig, request_id: str) -> tuple[str, int, list[int]]; now async def... pypi.org
• Signature changed transformers.cli.serving.chat_completion.BaseGenerateManager.generate_streaming
  Was def generate_streaming(self, model: PreTrainedModel, processor: ProcessorMixin | PreTrainedTokenizerFast, inputs: dict, gen_config: GenerationConfig, request_id: str) -> tuple[asyncio.Queue, DirectStreamer | CBStreamer]; now def... pypi.org

And 64 more in this version.

5.5.2

1 breaking change, first published April 9, 2026.

• Behavior changed
  Gemma4 no longer stores shared weights, and loading silently skips them instead of erroring. Code that reads or expects those weight names may need to change. github.com

5.5.1

2 breaking changes, first published April 9, 2026.

• Signature changed transformers.Cache.early_initialization
  Was def early_initialization(self, batch_size: int, num_heads: int, head_dim: int, dtype: torch.dtype, device: torch.device); now def early_initialization(self, batch_size: int, num_heads: int | list[int], head_dim: int | list[int], dtype... pypi.org
• Signature changed transformers.RopeParameters.rope_theta
  Was rope_theta: float; now rope_theta: float | None. pypi.org

Check your code

These are the changes. To see which of them reach your code, scan a public repository, or have your coding agent call check_code with your manifest or lockfile over MCP. The API reads every change in every version, not only the newest. On Team and up, a fix pull request opens for the changes that reach a connected repository. Nothing merges or deploys.