Snapshot 2026-08-04 16:17:00 UTC · version 1
Unsloth is a fast-kernel wrapper over PEFT and TRL, not a replacement API — every Unsloth kwarg below has a plain TRL/PEFT equivalent. Use this table to translate an Unsloth config to plain TRL (or back), and to know which knob lives on which object in the current TRL API. Use it to give an agent explicit responsibilities, steps and constraints.
Unsloth is a fast-kernel wrapper over PEFT and TRL, not a replacement API — every Unsloth kwarg below has a plain TRL/PEFT equivalent. Use this table to translate an Unsloth config to plain TRL (or back), and to know which knob lives on which object in the current TRL API. Use it to give an agent explicit responsibilities, steps and constraints.
Editorial note: curated source snapshot published by Collider.club under the MIT License. Source attribution is preserved in the front matter.
Last verified: 2026-07-14
Unsloth is a fast-kernel wrapper over PEFT and TRL, not a replacement API — every Unsloth kwarg below has a plain TRL/PEFT equivalent. Use this table to translate an Unsloth config to plain TRL (or back), and to know which knob lives on which object in the current TRL API.
| Unsloth kwarg | TRL/PEFT equivalent | Notes |
|---|---|---|
FastLanguageModel.from_pretrained(model_name=...) |
AutoModelForCausalLM.from_pretrained(...) + AutoTokenizer.from_pretrained(...) |
Unsloth fuses model+tokenizer load with kernel patching in one call. |
load_in_4bit=True |
BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4", bnb_4bit_compute_dtype=torch.bfloat16) passed to from_pretrained |
This is the QLoRA path in both. |
FastLanguageModel.get_peft_model(r=..., target_modules=..., lora_alpha=..., lora_dropout=..., bias=..., random_state=...) |
peft.LoraConfig(r=..., target_modules=..., lora_alpha=..., lora_dropout=..., bias=...) + peft.get_peft_model(model, config); random_state → seed set before get_peft_model |
Unsloth's call is a thin wrapper generating the same LoraConfig under the hood. |
use_gradient_checkpointing="unsloth" |
gradient_checkpointing=True in SFTConfig/TrainingArguments |
Unsloth's variant is a faster/lower-memory implementation of the same idea — not a different feature. Plain TRL's gradient_checkpointing=True is the correct fallback, just with less VRAM savings (~30% less benefit). |
optim="adamw_8bit" |
SFTConfig(optim="adamw_8bit") |
Identical string, same bitsandbytes optimizer — no translation needed. |
use_rslora=True/False |
LoraConfig(use_rslora=True/False) |
Same flag name in PEFT directly. |
max_seq_length (passed to FastLanguageModel.from_pretrained) |
SFTConfig(max_length=...) |
Current TRL: the field is max_length on SFTConfig (renamed from max_seq_length), not on the trainer call or from_pretrained in plain TRL. |
dataset_text_field (Unsloth examples often set this on the trainer) |
SFTConfig(dataset_text_field=...) |
Current TRL: lives on SFTConfig, same as max_seq_length. |
random_state=3407 (data/adapter-init seed) |
SFTConfig(seed=3407) for trainer-level seeding |
Set both — Unsloth's random_state seeds LoRA init specifically; SFTConfig.seed seeds the trainer's own RNG use. |
Two API surfaces changed recently enough that stale examples (including some Unsloth cookbook snippets) still show the old form:
processing_class, not tokenizer=.
SFTTrainer(tokenizer=tokenizer, ...) is the
old, removed-or-deprecated form. Current TRL
takes SFTTrainer(processing_class=tokenizer, ...). If a config or example still passes
tokenizer=, update it before running — this
is the single most common stale-API error when
porting an older recipe forward.max_length (renamed from max_seq_length)
and dataset_text_field live in SFTConfig, not
scattered across the trainer call or the model
loader. Set them once, on the SFTConfig
instance, and don't
duplicate them elsewhere in the pipeline.Four confirmed gaps on Unsloth 2026.7.2 (transformers 5.13.1, trl 1.8.0), found while training a real messages-shaped SFT run. None of these are hypothetical — each was reproduced with a live load/train and, where noted, a working fix.
assistant_only_loss=TrueUnsloth's compiled SFTTrainer (monkeypatched onto
trl.SFTTrainer process-wide the moment unsloth is
imported anywhere — not reversible within the process,
and not gated on FastLanguageModel actually being
used) ships a hand-written _prepare_dataset that
recognizes exactly four dataset shapes by column name:
pre-tokenized (input_ids/labels), prompt+
completion, a flat dataset_text_field, or a
formatting_func returning pre-rendered strings.
There is no messages-shaped conversational-dataset
path at all. A formatting_func can only return flat
text, which forces pre-rendering the chat template
before the trainer sees per-turn boundaries — the exact
flat-text anti-pattern dataset-curation's
references/formats-and-templates.md warns computes
loss over the entire sequence, defeating
assistant_only_loss's purpose. Fix: use the plain
TRL + PEFT escape hatch below — this is not a rare
point-release regression to wait out, it is the current
state of Unsloth 2026.7.x for this exact combination
(messages dataset + assistant_only_loss=True + no
packing). Confirmed via two independent runs:
Unsloth's path raises immediately at trainer
construction; identical hyperparameters run cleanly
end-to-end once unsloth is never imported and plain
transformers.AutoModelForCausalLM +
peft.LoraConfig/get_peft_model + trl.SFTTrainer
are used instead.
attn_implementation kwarg silently droppedFastLanguageModel.from_pretrained(..., attn_implementation="sdpa") does not reliably force
SDPA. Unsloth's loader calls its own attention-resolution
helper without forwarding the caller's
attn_implementation, then discards the kwarg outright —
so a flash-attn build that's importable gets auto-selected
regardless of what was requested. Confirmed: passing
attn_implementation="sdpa" explicitly still resolved to
model.config._attn_implementation == "flash_attention_2". The only working override is a
monkeypatch before calling from_pretrained — scope it
tightly, since HAS_FLASH_ATTENTION is a module-global
that also affects any other from_pretrained call made
later in the same process (a second model load in the same
script or notebook cell inherits whatever the flag was last
set to, silently):
import unsloth.models._utils as unsloth_utils
_original = unsloth_utils.HAS_FLASH_ATTENTION
try:
unsloth_utils.HAS_FLASH_ATTENTION = False
model, tokenizer = FastLanguageModel.from_pretrained(...)
assert model.config._attn_implementation == "sdpa", (
f"expected sdpa, got {model.config._attn_implementation}"
)
finally:
unsloth_utils.HAS_FLASH_ATTENTION = _original
This forces the resolver down its SDPA branch for the
duration of the try block only, restores the prior value
in finally even if from_pretrained raises, and asserts
the resolver actually landed on SDPA rather than silently
falling through. On plain TRL/PEFT (the escape hatch
above), attn_implementation="sdpa" passed to
AutoModelForCausalLM.from_pretrained is honored
correctly — this is an Unsloth-specific gap, not a general
TRL issue.
padding_free collision with a plain-TRL SFTConfigPassing a plain trl.SFTConfig(max_length=1024, packing=False, ...) (i.e., not touching padding_free,
matching TRL's own documented default of
padding_free=False) into Unsloth's compiled trainer can
still raise ValueError: When padding_free=True without packing, max_length is not enforced.... Unsloth's own
compiled SFTConfig-equivalent dataclass defaults
padding_free = None, and something in its resolution
path turns that into a truthy value even for an args
instance built from plain trl.SFTConfig. Fix: pass
padding_free=False explicitly whenever training
through Unsloth — cheap insurance regardless of which path
you're on.
Before raising the "template lacks {% generation %}"
error described in dataset-curation SKILL.md, TRL 1.8.0's
SFTTrainer.__init__ calls an internal
get_training_chat_template() that tries to swap in one of
~18 hardcoded known-model training templates
(trl.chat_template_utils) keyed on exact string
equality against the tokenizer's chat_template. If the
model's shipped template doesn't literal-match a table
entry — even a near-identical one — the auto-patch silently
fails to apply and TRL raises. Fix pattern: hand-patch a
copy of the tokenizer's actual template by wrapping the
assistant-turn content span with {% generation %}... {% endgeneration %} markers — role marker outside the
span, the end-of-turn token inside it (matching TRL's
is_chat_template_stop_token_trained check) — preserving
every branch of the real template (tool-calling, per-turn
special-case handling) that a generic fallback constant
won't have. Load the patched template into
tokenizer.chat_template in memory only; never overwrite
the base model directory's shipped template file.
For messages-shaped SFT with assistant_only_loss=True,
this is the default path per the Known Limitations
section above, not a fallback of last resort. For every
other training mode, Unsloth ships fast point releases and
a point release occasionally regresses a specific mode (a
collator, a chunked-loss path, a particular model
architecture) before the next patch fixes it. Either way:
This is why the mapping table exists: it makes the fallback mechanical instead of a from-scratch rewrite.
This card belongs to the curated knowledge base of Collider.club — a closed business club for entrepreneurs, engineers, investors and domain experts building projects for international markets. Members work across DeFi, AI/ML, FinTech, Web3, banking, hardware and venture capital, and the club runs closed sessions on high-margin niches with anonymous speakers.
mdrss-card/v2)MIT License — Copyright (c) 2026 Collider.club. Full text: LICENSE · https://opensource.org/licenses/MIT
concept:training-fine-tuningorg:collider-club Sign in to join the discussion.
Snapshot 2026-08-04 16:17:00 UTC · version 1
Unsloth is a fast-kernel wrapper over PEFT and TRL, not a replacement API — every Unsloth kwarg below has a plain TRL/PEFT equivalent. Use this table to translate an Unsloth config to plain TRL (or back), and to know which knob lives on which object in the current TRL API. Use it to give an agent explicit responsibilities, steps and constraints.
Unsloth is a fast-kernel wrapper over PEFT and TRL, not a replacement API — every Unsloth kwarg below has a plain TRL/PEFT equivalent. Use this table to translate an Unsloth config to plain TRL (or back), and to know which knob lives on which object in the current TRL API. Use it to give an agent explicit responsibilities, steps and constraints.
Editorial note: curated source snapshot published by Collider.club under the MIT License. Source attribution is preserved in the front matter.
Last verified: 2026-07-14
Unsloth is a fast-kernel wrapper over PEFT and TRL, not a replacement API — every Unsloth kwarg below has a plain TRL/PEFT equivalent. Use this table to translate an Unsloth config to plain TRL (or back), and to know which knob lives on which object in the current TRL API.
| Unsloth kwarg | TRL/PEFT equivalent | Notes |
|---|---|---|
FastLanguageModel.from_pretrained(model_name=...) |
AutoModelForCausalLM.from_pretrained(...) + AutoTokenizer.from_pretrained(...) |
Unsloth fuses model+tokenizer load with kernel patching in one call. |
load_in_4bit=True |
BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4", bnb_4bit_compute_dtype=torch.bfloat16) passed to from_pretrained |
This is the QLoRA path in both. |
FastLanguageModel.get_peft_model(r=..., target_modules=..., lora_alpha=..., lora_dropout=..., bias=..., random_state=...) |
peft.LoraConfig(r=..., target_modules=..., lora_alpha=..., lora_dropout=..., bias=...) + peft.get_peft_model(model, config); random_state → seed set before get_peft_model |
Unsloth's call is a thin wrapper generating the same LoraConfig under the hood. |
use_gradient_checkpointing="unsloth" |
gradient_checkpointing=True in SFTConfig/TrainingArguments |
Unsloth's variant is a faster/lower-memory implementation of the same idea — not a different feature. Plain TRL's gradient_checkpointing=True is the correct fallback, just with less VRAM savings (~30% less benefit). |
optim="adamw_8bit" |
SFTConfig(optim="adamw_8bit") |
Identical string, same bitsandbytes optimizer — no translation needed. |
use_rslora=True/False |
LoraConfig(use_rslora=True/False) |
Same flag name in PEFT directly. |
max_seq_length (passed to FastLanguageModel.from_pretrained) |
SFTConfig(max_length=...) |
Current TRL: the field is max_length on SFTConfig (renamed from max_seq_length), not on the trainer call or from_pretrained in plain TRL. |
dataset_text_field (Unsloth examples often set this on the trainer) |
SFTConfig(dataset_text_field=...) |
Current TRL: lives on SFTConfig, same as max_seq_length. |
random_state=3407 (data/adapter-init seed) |
SFTConfig(seed=3407) for trainer-level seeding |
Set both — Unsloth's random_state seeds LoRA init specifically; SFTConfig.seed seeds the trainer's own RNG use. |
Two API surfaces changed recently enough that stale examples (including some Unsloth cookbook snippets) still show the old form:
processing_class, not tokenizer=.
SFTTrainer(tokenizer=tokenizer, ...) is the
old, removed-or-deprecated form. Current TRL
takes SFTTrainer(processing_class=tokenizer, ...). If a config or example still passes
tokenizer=, update it before running — this
is the single most common stale-API error when
porting an older recipe forward.max_length (renamed from max_seq_length)
and dataset_text_field live in SFTConfig, not
scattered across the trainer call or the model
loader. Set them once, on the SFTConfig
instance, and don't
duplicate them elsewhere in the pipeline.Four confirmed gaps on Unsloth 2026.7.2 (transformers 5.13.1, trl 1.8.0), found while training a real messages-shaped SFT run. None of these are hypothetical — each was reproduced with a live load/train and, where noted, a working fix.
assistant_only_loss=TrueUnsloth's compiled SFTTrainer (monkeypatched onto
trl.SFTTrainer process-wide the moment unsloth is
imported anywhere — not reversible within the process,
and not gated on FastLanguageModel actually being
used) ships a hand-written _prepare_dataset that
recognizes exactly four dataset shapes by column name:
pre-tokenized (input_ids/labels), prompt+
completion, a flat dataset_text_field, or a
formatting_func returning pre-rendered strings.
There is no messages-shaped conversational-dataset
path at all. A formatting_func can only return flat
text, which forces pre-rendering the chat template
before the trainer sees per-turn boundaries — the exact
flat-text anti-pattern dataset-curation's
references/formats-and-templates.md warns computes
loss over the entire sequence, defeating
assistant_only_loss's purpose. Fix: use the plain
TRL + PEFT escape hatch below — this is not a rare
point-release regression to wait out, it is the current
state of Unsloth 2026.7.x for this exact combination
(messages dataset + assistant_only_loss=True + no
packing). Confirmed via two independent runs:
Unsloth's path raises immediately at trainer
construction; identical hyperparameters run cleanly
end-to-end once unsloth is never imported and plain
transformers.AutoModelForCausalLM +
peft.LoraConfig/get_peft_model + trl.SFTTrainer
are used instead.
attn_implementation kwarg silently droppedFastLanguageModel.from_pretrained(..., attn_implementation="sdpa") does not reliably force
SDPA. Unsloth's loader calls its own attention-resolution
helper without forwarding the caller's
attn_implementation, then discards the kwarg outright —
so a flash-attn build that's importable gets auto-selected
regardless of what was requested. Confirmed: passing
attn_implementation="sdpa" explicitly still resolved to
model.config._attn_implementation == "flash_attention_2". The only working override is a
monkeypatch before calling from_pretrained — scope it
tightly, since HAS_FLASH_ATTENTION is a module-global
that also affects any other from_pretrained call made
later in the same process (a second model load in the same
script or notebook cell inherits whatever the flag was last
set to, silently):
import unsloth.models._utils as unsloth_utils
_original = unsloth_utils.HAS_FLASH_ATTENTION
try:
unsloth_utils.HAS_FLASH_ATTENTION = False
model, tokenizer = FastLanguageModel.from_pretrained(...)
assert model.config._attn_implementation == "sdpa", (
f"expected sdpa, got {model.config._attn_implementation}"
)
finally:
unsloth_utils.HAS_FLASH_ATTENTION = _original
This forces the resolver down its SDPA branch for the
duration of the try block only, restores the prior value
in finally even if from_pretrained raises, and asserts
the resolver actually landed on SDPA rather than silently
falling through. On plain TRL/PEFT (the escape hatch
above), attn_implementation="sdpa" passed to
AutoModelForCausalLM.from_pretrained is honored
correctly — this is an Unsloth-specific gap, not a general
TRL issue.
padding_free collision with a plain-TRL SFTConfigPassing a plain trl.SFTConfig(max_length=1024, packing=False, ...) (i.e., not touching padding_free,
matching TRL's own documented default of
padding_free=False) into Unsloth's compiled trainer can
still raise ValueError: When padding_free=True without packing, max_length is not enforced.... Unsloth's own
compiled SFTConfig-equivalent dataclass defaults
padding_free = None, and something in its resolution
path turns that into a truthy value even for an args
instance built from plain trl.SFTConfig. Fix: pass
padding_free=False explicitly whenever training
through Unsloth — cheap insurance regardless of which path
you're on.
Before raising the "template lacks {% generation %}"
error described in dataset-curation SKILL.md, TRL 1.8.0's
SFTTrainer.__init__ calls an internal
get_training_chat_template() that tries to swap in one of
~18 hardcoded known-model training templates
(trl.chat_template_utils) keyed on exact string
equality against the tokenizer's chat_template. If the
model's shipped template doesn't literal-match a table
entry — even a near-identical one — the auto-patch silently
fails to apply and TRL raises. Fix pattern: hand-patch a
copy of the tokenizer's actual template by wrapping the
assistant-turn content span with {% generation %}... {% endgeneration %} markers — role marker outside the
span, the end-of-turn token inside it (matching TRL's
is_chat_template_stop_token_trained check) — preserving
every branch of the real template (tool-calling, per-turn
special-case handling) that a generic fallback constant
won't have. Load the patched template into
tokenizer.chat_template in memory only; never overwrite
the base model directory's shipped template file.
For messages-shaped SFT with assistant_only_loss=True,
this is the default path per the Known Limitations
section above, not a fallback of last resort. For every
other training mode, Unsloth ships fast point releases and
a point release occasionally regresses a specific mode (a
collator, a chunked-loss path, a particular model
architecture) before the next patch fixes it. Either way:
This is why the mapping table exists: it makes the fallback mechanical instead of a from-scratch rewrite.
This card belongs to the curated knowledge base of Collider.club — a closed business club for entrepreneurs, engineers, investors and domain experts building projects for international markets. Members work across DeFi, AI/ML, FinTech, Web3, banking, hardware and venture capital, and the club runs closed sessions on high-margin niches with anonymous speakers.
mdrss-card/v2)MIT License — Copyright (c) 2026 Collider.club. Full text: LICENSE · https://opensource.org/licenses/MIT
concept:training-fine-tuningorg:collider-club Sign in to join the discussion.