Unsloth Fine-Tuning

Overview

Unsloth trains LLMs with custom kernels that cut VRAM use and step time without changing the math, which makes single-GPU fine-tuning practical on hardware that would otherwise OOM. This skill covers Unsloth Core — the Python API — because that is what an agent can drive programmatically; the Desktop app and Studio web UI are interactive and out of scope.

The hard parts of an Unsloth run are not the training call. They are sizing the job against available VRAM, getting the chat template and loss masking right, and choosing an export format the target runtime can actually load. This skill covers those three.

When to Use This Skill

• Use when fine-tuning an LLM on one GPU and VRAM is the binding constraint.
• Use when a training run OOMs and needs to be resized rather than rewritten.
• Use when doing preference or RL post-training (GRPO, DPO) on consumer hardware.
• Use when a fine-tuned model must be exported to GGUF, vLLM, or merged 16-bit weights.
• Use when a fine-tune "ran fine" but the model's output format is wrong — usually a chat template or loss-masking bug, not a hyperparameter one.

Do not use this skill when

• The training is multi-node or large-scale multi-GPU. Use plain TRL with Accelerate/DeepSpeed.
• The architecture is unsupported by Unsloth. Fall back to TRL; do not force it.
• The user wants managed cloud training. That is Hugging Face Jobs, not local Unsloth.
• The user wants the Desktop or Studio GUI. Point them at the installer, not this skill.

How It Works

Step 1: Size the run before writing code

VRAM is the constraint that decides everything else. Estimate weights first, then leave room for activations and optimizer state:

Add roughly 2-6 GB for activations, scaling with max_seq_length and batch size. Treat these as planning figures and confirm against nvidia-smi on the first run — they vary by architecture, attention implementation and vocabulary size.

If the estimate does not fit, reduce in this order: max_seq_length, then batch size (raising gradient_accumulation_steps to hold the effective batch constant), then LoRA rank, then model size. Cutting rank before sequence length usually costs more quality than it saves memory.

Step 2: Load the model

import unsloth must come before transformers, trl or peft. Unsloth patches those libraries at import time; importing them first silently disables the optimizations.

import unsloth  # must be first
import os
import re
from unsloth import FastLanguageModel

def reviewed_revision(variable):
    revision = os.environ.get(variable, "")
    if re.fullmatch(r"[0-9a-fA-F]{40}", revision) is None:
        raise RuntimeError(f"{variable} must be a reviewed full 40-character Hub commit SHA")
    return revision.lower()

model_revision = reviewed_revision("UNSLOTH_MODEL_REVISION")
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/Qwen3-8B",
    revision = model_revision,
    max_seq_length = 2048,
    load_in_4bit = True,
    dtype = None,  # auto-detects bf16 where supported
)

Pick the loader that matches the modality: FastLanguageModel for text-only causal LMs, FastVisionModel for vision-language models, FastModel when the modality is decided at runtime.

The unsloth/ Hub namespace holds pre-quantized copies that download faster and skip a local quantization pass. Upstream repos such as Qwen/ or meta-llama/ work identically. Before setting UNSLOTH_MODEL_REVISION, inspect that exact Hub commit and obtain approval for the download. Record the repository and full revision with the run; never substitute a branch, tag, range, or moving default.

Step 3: Fix the chat template before training

This is the most common silent failure. A run with the wrong template converges cleanly and produces a model that ignores its stop tokens or emits prompt scaffolding at inference.

from unsloth.chat_templates import (
    get_chat_template,
    standardize_data_formats,

…