[Feature] Provide official way to install with transformers 5.x (extra ideally or env var)

[Maxusmusti]

Summary

Transformers 5.x support is documented as available (December release notes, Issue #3786), but the pyproject.toml constraint blocks installation:

transformers>4.51.3,...,<=4.57.6

This makes it impossible to install unsloth alongside packages that require transformers>=5.0.0 without workarounds like --no-deps.

Request

Provide an official mechanism to opt-in to transformers 5.x support. Two options:

Option A: New extra

  [project.optional-dependencies]
  transformers5 = [
      "transformers>=5.0.0",
  ]

Install with:
pip install unsloth[transformers5]

This option would likely be the easiest, both to add and maintain, as well as for people looking for an easy addition to their own pyproject.toml, requirements, scripts, etc.

Option B: Environment variable bypass

(In setup/pyproject)
if os.environ.get("UNSLOTH_ALLOW_TRANSFORMERS5"):
# Skip version constraint check

Why This Matters

• Issue Support for TRL GRPOTrainer with tools= argument (requires transformers 5.0) #3786 is closed as completed, indicating the code is compatible
• December release notes state "Transformers v5 is now supported"
• Users integrating unsloth into larger projects can't use it if other dependencies require transformers 5.x
• Current workaround (pip install unsloth --no-deps) is fragile and undocumented

Environment

• unsloth 2026.2.1
• transformers 5.x required by dependent package
• uv/pip fails to resolve dependencies

References

• December Release Discussion: December Release #3749 ("Transformers v5 is now supported! It's not enabled by default due to possible instability issues.")
• Closed issue confirming compatibility: Support for TRL GRPOTrainer with tools= argument (requires transformers 5.0) #3786

[Datta0]

Hey @Maxusmusti we're still ironing out some issues with transformers v5 changes. It was a big release so we need some more time.
Meanwhile, you can simply install unsloth and then later upgrade transformers. Nothing would stop you from doing that

[Maxusmusti]

Hi @Datta0, I see, thanks for the response! I understand that you can manually get both to install together, but in our case we have unsloth as a dependency that needs to be included in our requirements for another package , and we need it to build/resolve alongside other packages that now require transformers v5 in their latest releases. Do you have an idea as to when an optional extra or new release that allows resolution with v5 will be out? This will help us greatly in our roadmap and release planning, thanks!

[sudo-0x2a]

Hey @Maxusmusti we're still ironing out some issues with transformers v5 changes. It was a big release so we need some more time. Meanwhile, you can simply install unsloth and then later upgrade transformers. Nothing would stop you from doing that

Appreciate your efforts! I recommend no rush because the vllm has not support the v5 as well. I think it would be better to release the support after the vllm so the whole technique stack can be consistent.

[wektorz]

Hey @Maxusmusti we're still ironing out some issues with transformers v5 changes. It was a big release so we need some more time. Meanwhile, you can simply install unsloth and then later upgrade transformers. Nothing would stop you from doing that

Appreciate your efforts! I recommend no rush because the vllm has not support the v5 as well. I think it would be better to release the support after the vllm so the whole technique stack can be consistent.

vllm has transfomers v5 support now in 0.19.1 ;)

[Datta0]

Imma go ahead and close this issue now.