---
name: transformers-upgrade
description: "Playbook for changing vLLM's Transformers version bounds. Use when bumping the pinned or maximum Transformers version, raising the minimum Transformers version, or deleting vendored configs, processors, or compat shims that upstream Transformers now provides."
title: transformers-upgrade
canonical_url: https://skilld.dev/gh/vllm-project/vllm/transformers-upgrade
last_updated: 2026-10-20T01:04:57.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/vllm-project/vllm/transformers-upgrade/agents/openai.yaml), [scripts/diff_dumps.py](https://skilld.dev/api/skills-raw/vllm-project/vllm/transformers-upgrade/scripts/diff_dumps.py), [scripts/dump_configs.py](https://skilld.dev/api/skills-raw/vllm-project/vllm/transformers-upgrade/scripts/dump_configs.py), [scripts/dump_model.py](https://skilld.dev/api/skills-raw/vllm-project/vllm/transformers-upgrade/scripts/dump_model.py), [scripts/find_upstreamed.py](https://skilld.dev/api/skills-raw/vllm-project/vllm/transformers-upgrade/scripts/find_upstreamed.py).
>
> If the user asked to install this Skill, run `npx skilld install vllm-project/vllm/transformers-upgrade`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/transformers-upgrade`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/vllm-project/vllm/transformers-upgrade) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/transformers-upgrade`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/transformers-upgrade --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/transformers-upgrade --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Upgrading Transformers

The supported range lives in `requirements/common.txt`. CI pins one exact
version in `requirements/test/*.in` and the compiled `requirements/test/*.txt`.
A version change is one of two jobs, and they usually come as a pair:

- **Bump the pin**: a new Transformers release becomes the CI version and
  the upper bound. vLLM grows compat code for it.
- **Raise the floor**: the minimum moves up. That compat code, and every
  vendored config or processor upstream now ships, becomes dead weight.
  Every floor raise ends with an **unvendoring pass**.

## Bump the pin

1. Edit the pin line in each `requirements/test/*.in` and `*.txt` and the
   upper bound in `requirements/common.txt`. Past bumps edit only the pin
   line in the compiled files; see `git log -- requirements/common.txt`.
2. Read the release notes for config validation changes, renamed auto-mapping
   formats, and removed attributes; these are what break vLLM.
3. Search `tests/` for `min_transformers_version` and skip markers naming the
   new version, and run those tests on the new pin. Keep the gates: older
   versions in the supported range still lack the feature, so a gate goes
   only when the floor reaches it.
4. Run the suites in [Testing](#testing) and fix what breaks. Mark every
   shim with a `# Transformers >= X` comment so the next floor raise finds it.

Done when the [Testing](#testing) suites and every test gated on this
version pass on the new pin.

## Raise the floor (unvendoring pass)

### 1. Inventory

Inventory candidates with the floor version installed (no vLLM install needed):

```bash
uv run --no-project --with transformers==<floor> \
    python .agents/skills/transformers-upgrade/scripts/find_upstreamed.py
```

It lists:

- vendored configs whose `model_type` upstream now owns;
- `_CONFIG_REGISTRY` overrides of upstream types;
- registered processors that collide with upstream class names or models;
- version-gated code at or below the floor;
- code that reads the installed Transformers version, whatever its threshold;
- patches citing a Transformers issue or PR (with whether a referenced PR is
  in the floor release) or a future minimum version.

It finds candidates by name only. Every hit still needs a verdict.

### 2. Port each candidate to upstream

Every hit is deleted by default. A vendored copy is a liability: it drifts
from upstream, hides upstream fixes, and shadows the native class. Port the
vLLM model code to the upstream schema instead, renaming attribute reads and
deriving values from upstream fields.

Fan candidates out to parallel subagents. Each one compares the vendored and
upstream classes, then greps every attribute the vLLM model code reads.
[Upstreaming hazards](#upstreaming-hazards) lists the usual fixes.

Keep a vendored class only when upstream cannot load a checkpoint vLLM must
keep serving, and record why in the PR description. A different upstream
schema, a model-code rewrite, or a needed eval is work for the PR, not a
reason to keep.

### 3. Prove it on real checkpoints

For every checkpoint in `tests/models/registry.py` that uses a ported
config, dump what vLLM builds before and after the change, then diff the two.
Run both dumps; each catches what the other misses:

- `dump_configs.py`: the resolved config, attribute by attribute.
- `dump_model.py`: the model built on the meta device with no GPU or weights.
  It records ModelConfig sizes, every parameter shape, and every module's
  scalar attributes (`head_dim`, `num_kv_heads`, `scaling`, ...). Missing
  fields that are read with defaults only show up here.

```bash
git worktree add --detach <scratch>/vllm-base upstream/main
S=.agents/skills/transformers-upgrade/scripts
for dump in dump_configs dump_model; do
    PYTHONPATH=<scratch>/vllm-base .venv/bin/python $S/$dump.py before.jsonl <repos>
    PYTHONPATH=$PWD .venv/bin/python $S/$dump.py after.jsonl <repos>
    .venv/bin/python $S/diff_dumps.py before.jsonl after.jsonl
done
```

Add `--trust-remote-code` for checkpoints whose `config.json` has an
`auto_map`, and dump both ways.

How to read the diffs:

- **A `<MISSING>` config field the model reads:** this crashes or silently
  falls back to a default. Port the model code to the upstream field.
- **New upstream-only defaults** (`attention_bias=False`,
  `pad_token_id=None`): usually benign. A model diff of 0 confirms it.
- **Any model diff:** this is a numerics change, and the PR needs a model
  eval. For example, A.X-K1 gained the checkpoint's YaRN rope scaling, which
  the vendored class had been dropping; it shows up as
  `layers.*.self_attn.scaling (x61)`.

### 4. Delete

For each deleted config:

- Delete the file.
- Remove its entries from `_CLASS_TO_MODULE` and `__all__` in
  `vllm/transformers_utils/configs/__init__.py`.
- Remove its entries from `_CONFIG_REGISTRY` in
  `vllm/transformers_utils/config.py`.
- Switch every importer, including tests, to `from transformers import ...`.
- Remove the `source_file_dependencies` lines naming the file from
  `.buildkite/`.

Deleted processors follow the same steps in
`vllm/transformers_utils/processors/__init__.py`.

Before merging, rebase and grep again for the old field names: PRs that land
in between still read them.

Done when every line of the inventory output is deleted, or kept with a
reason that meets the bar in step 2. The PR also carries the config diff
results and evals for any changed values.

## Upstreaming hazards

Upstream configs are `@strict` dataclasses. Checkpoint keys upstream does not
declare survive as plain attributes, but only when the checkpoint sets them.
Defaults that only vLLM sets, and values vLLM derives, vanish.

| Hazard | Signal | Fix |
| --- | --- | --- |
| Upstream consumes legacy keys | `__post_init__` pops keys the model reads (`deepseek_v4` `compress_ratios`) | Read the upstream replacement (`layer_types`, `mlp_layer_types`, per-layer `rope_parameters`) |
| Renamed or dropped fields | Diff shows `<MISSING>` for a field the model reads | Read the upstream name; derive dropped flags from what implies them (`enable_moe_block` from `num_experts`) |
| Undeclared field without a default | `config.x` raises `AttributeError` for configs that omit `x`, e.g. minimal test configs (A.X-K1 `scoring_func`). Dumps of real checkpoints miss it | Upstream ignoring `x` usually means vLLM can stop reading it; if vLLM truly needs it, read `getattr(config, "x", <old default>)` |
| Top-level config stops forwarding | The vendored top-level config forwarded reads to `text_config`; upstream does not. `getattr(config, "x", default)` silently takes the default, e.g. on MTP draft configs from `SpeculativeConfig.hf_config_override`, which the dumps do not build | Read from `get_text_config()`; grep `getattr` reads of every field, including speculative-decoding paths |
| Type check on the config | `ctx.get_hf_config(SomeConfig)` relies on the vendored base class | Accept the upstream class too, e.g. a `Cosmos3ProcessingInfo` overriding `get_hf_config` |
| Remote code takes over | Checkpoint `config.json` has `auto_map`; with `--trust-remote-code`, the hub class replaces the native one once vLLM stops registering its own | Check the remote class loads; if not, register the upstream class for that `model_type` |
| Read-only upstream fields | Properties or derived fields break subclasses and `hf_overrides` (`nemotron_h` `hybrid_override_pattern`) | Override the source field (`layers_block_type`) instead |
| Behavioural rewrite | Upstream derives fields differently (`diffusion_gemma` `sliding_window`) | Upstream matches the reference implementation; verify with an eval |
| Original checkpoint format | Upstream targets `-hf` conversions; vLLM serves the originals (`qwen3_asr`, `qianfan_ocr`) | Keep only if upstream cannot load the original at all |
| Processor output contract | Model code consumes keys upstream does not emit | Port the model to upstream's keys |
| Name collision | A registered vendored processor shares an upstream class name and hijacks `get_processor` (`InternVLProcessor`) | Drop the registry entry |

Version gates from the inventory need a decision:

- **Code** only reachable below the floor is deleted. This covers:
    - comparisons against `TRANSFORMERS_VERSION`;
    - branches labelled `# Transformers < X`;
    - fallbacks for fields that upstream configs now always set, e.g.
    `mlp_layer_types`, `per_layer_config` or legacy `layer_types` names.

  A `skipif` whose condition is now always true becomes an unconditional
  `skip` with the same reason.
- **`min_transformers_version`** at or below the floor is removed.
- **`max_transformers_version`** below the floor means CI never tests that
  model; report it rather than deleting it silently.
- **Patches citing a Transformers issue or PR:**
    - Delete the patch when its fix is in the floor release.
    - For an issue, find the PR that closed it and check that PR. A closed
      issue is not a fixed one: issues get closed while the bug is still in
      the release.
    - Re-run the patched behaviour before deleting. A fix in the release does
      not always cover vLLM's path: Emu3's processor gained BOS upstream, but
      vLLM tokenizes without the processor.
    - Links that only explain a design choice (e.g. a float32 RoPE note) are
      not patches; leave them.

## Testing

```bash
.venv/bin/python -m pytest tests/transformers_utils tests/config tests/tokenizers_
.venv/bin/python -m pytest tests/models/multimodal/processing/test_common.py -k "<models>"
```

Add `tests/models/test_initialization.py -k "<archs>"` where a GPU is
available, and a model eval for any model whose resolved config changed.

Models in `vllm/models/` are high priority: whenever their config or model
code changes, run GSM8k (`tests/evals/gsm8k/`) and GPQA Diamond
(`tests/evals/gpt_oss/`) on `main` and the branch, even when the dumps show
no diff, and put both scores in the PR. FlashInfer autotuning picks kernel
tactics afresh on every server start, which moved DeepSeek-V4-Flash GSM8k by
about 1 point; pass `--kernel-config '{"enable_flashinfer_autotune": false}'`
to both servers so greedy outputs are comparable.
