# Using Unsloth for Faster Training with Reduced VRAM: A Complete Guide

> Accelerate your AI training with Unsloth. Cut VRAM usage by 60% and double speeds using optimized kernels and 4-bit quantization. Learn how in this complete guide.

- Repository: [Hugging Face/skills](https://github.com/huggingface/skills)
- Tags: how-to-guide
- Published: 2026-03-08

---

**Unsloth reduces VRAM consumption by approximately 60% and doubles training speed compared to standard TRL workflows by leveraging optimized kernels, 4-bit quantization, and custom gradient checkpointing.**

The `huggingface/skills` repository provides a production-ready implementation of Unsloth through the `hugging-face-model-trainer` skill, enabling developers to fine-tune large language models efficiently on consumer GPUs or cloud infrastructure. This guide explains how to use Unsloth for faster training with reduced VRAM using the official skill scripts and reference implementations.

## What Is Unsloth and Why Use It for LLM Fine-Tuning?

Unsloth is a high-performance wrapper around the 🤗 TRL (Transformer Reinforcement Learning) library that optimizes the entire fine-tuning pipeline. Unlike standard TRL workflows that load full-precision models into VRAM, Unsloth's `FastLanguageModel` class implements intelligent quantization, fused attention kernels, and memory-efficient gradient checkpointing.

According to the source code in [`skills/hugging-face-model-trainer/references/unsloth.md`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/references/unsloth.md), these optimizations yield approximately **60% VRAM reduction** and **2× faster training** compared to baseline TRL implementations, making it feasible to fine-tune 7B parameter models on 16GB consumer GPUs.

## How the Hugging Face Model Trainer Skill Implements Unsloth

### Architecture Overview

The skill follows a modular architecture where Unsloth-specific logic is encapsulated in dedicated scripts while maintaining compatibility with the broader Hugging Face ecosystem. The implementation resides in `skills/hugging-face-model-trainer/` and integrates with the `huggingface/skills` framework through standardized [`SKILL.md`](https://github.com/huggingface/skills/blob/main/SKILL.md) metadata files.

### Key Files and Their Roles

- **[`scripts/unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/scripts/unsloth_sft_example.py)** – The primary CLI entry point for Unsloth-based supervised fine-tuning (SFT). This UV-script-header file handles argument parsing, CUDA verification, Trackio logging integration, and the complete training orchestration.

- **[`references/unsloth.md`](https://github.com/huggingface/skills/blob/main/references/unsloth.md)** – Comprehensive documentation covering Unsloth installation, supported model architectures, vision-language model (VLM) support via `FastVisionModel`, and troubleshooting guides.

- **[`SKILL.md`](https://github.com/huggingface/skills/blob/main/SKILL.md)** – Metadata descriptor linking the capability to the script, specifying when to use Unsloth versus standard TRL.

- **[`scripts/train_sft_example.py`](https://github.com/huggingface/skills/blob/main/scripts/train_sft_example.py)** – Baseline TRL implementation useful for comparing memory usage and speed against the Unsloth workflow.

## Step-by-Step: Using Unsloth for Faster Training with Reduced VRAM

### Loading Models with FastLanguageModel

The Unsloth workflow begins with `FastLanguageModel.from_pretrained`, which replaces the standard `AutoModelForCausalLM` loader. This method automatically configures 4-bit quantization, 16-bit weights, and Unsloth-specific memory allocators.

```python
from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="LiquidAI/LFM2.5-1.2B-Instruct",
    max_seq_length=2048,
    dtype=None,  # Auto-detect float16/bfloat16

    load_in_4bit=True,  # Enable 4-bit quantization

)

```

As implemented in [`scripts/unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/scripts/unsloth_sft_example.py), the default model is `LiquidAI/LFM2.5-1.2B-Instruct`, though any compatible Hugging Face model can be substituted.

### Configuring LoRA Adapters

Unsloth simplifies LoRA (Low-Rank Adaptation) configuration through `FastLanguageModel.get_peft_model`. This single call replaces the multi-step PEFT workflow and automatically enables Unsloth's optimized gradient checkpointing.

```python
model = FastLanguageModel.get_peft_model(
    model,
    r=16,  # LoRA rank

    lora_alpha=16,
    target_modules=["q_proj", "k_proj", "v_proj", "out_proj", "in_proj", "w1", "w2", "w3"],
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing="unsloth",  # Optimized checkpointing

    random_state=3407,
)

```

The `use_gradient_checkpointing="unsloth"` parameter is critical for VRAM reduction, implementing a custom checkpointing strategy that trades minimal compute overhead for significant memory savings.

### Running Training with SFTTrainer

The training loop uses the standard `SFTTrainer` from TRL, but with Unsloth-optimized configuration passed through `SFTConfig`. The script in [`scripts/unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/scripts/unsloth_sft_example.py) demonstrates proper dataset formatting and training argument setup.

```python
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset

# Load and format dataset

dataset = load_dataset("mlabonne/FineTome-100k", split="train")

# Configure training with 8-bit optimizer

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    args=SFTConfig(
        output_dir="./output",
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        max_steps=500,
        learning_rate=2e-4,
        optim="adamw_8bit",  # Memory-efficient optimizer

        report_to="tensorboard",
    ),
)

trainer.train()

```

The `optim="adamw_8bit"` setting further reduces VRAM usage by quantizing optimizer states, complementing Unsloth's model-level optimizations.

## Command-Line Examples for Local and Cloud Training

The [`unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/unsloth_sft_example.py) script supports comprehensive CLI arguments for various deployment scenarios, from local development to Hugging Face Jobs.

### Quick Local Training

For rapid iteration on a development machine with CUDA support:

```bash
uv run scripts/unsloth_sft_example.py \
    --dataset mlabonne/FineTome-100k \
    --max-steps 500 \
    --output-repo your-username/model-finetuned

```

This command uses the UV script header defined in the file to automatically resolve dependencies and execute training with the default `LiquidAI/LFM2.5-1.2B-Instruct` model.

### Training with Evaluation and Tracking

To enable validation splits and real-time monitoring via Trackio:

```bash
uv run scripts/unsloth_sft_example.py \
    --dataset mlabonne/FineTome-100k \
    --num-epochs 1 \
    --eval-split 0.2 \
    --trackio-space your-username/trackio \
    --output-repo your-username/model-finetuned

```

The `--eval-split 0.2` parameter triggers `train_test_split` on the dataset, while `--trackio-space` injects `TRACKIO_SPACE_ID` into the environment and adds `"trackio"` to the `report_to` list in `SFTConfig`.

### Running on Hugging Face Jobs

For cloud GPU execution without managing infrastructure:

```bash
hf jobs uv run scripts/unsloth_sft_example.py \
    --flavor a10g-small --secrets HF_TOKEN --timeout 4h \
    -- --dataset mlabonne/FineTome-100k \
       --num-epochs 1 \
       --eval-split 0.2 \
       --output-repo your-username/model-finetuned

```

The double-dash (`--`) separates UV-specific arguments from script arguments. The `--flavor a10g-small` specifies GPU type, while `--secrets HF_TOKEN` ensures the Hugging Face token is available in the container environment for model pushing.

## Performance Comparison: Unsloth vs Standard TRL

The `huggingface/skills` repository includes both Unsloth and standard TRL implementations for direct comparison. The performance characteristics documented in [`skills/hugging-face-model-trainer/references/unsloth.md`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/references/unsloth.md) demonstrate significant advantages:

| Aspect | Standard TRL | Unsloth (`FastLanguageModel`) |
|--------|--------------|------------------------------|
| **Model Loading** | `AutoModelForCausalLM.from_pretrained` (full 16-bit) | Optimized 4-bit/8-bit loading with custom memory allocator |
| **LoRA Injection** | `PeftModel` + `LoraConfig` (multi-step) | Single-call `get_peft_model` with built-in gradient checkpointing |
| **VRAM Usage** | Baseline | ~60% reduction |
| **Training Speed** | Baseline | ~2× faster (fused kernels) |
| **Vision Support** | Limited | `FastVisionModel` + `UnslothVisionDataCollator` |

The VRAM savings stem from Unsloth's custom gradient checkpointing implementation (`use_gradient_checkpointing="unsloth"`), 4-bit quantization support, and 8-bit AdamW optimizer states. The speed improvements come from fused attention kernels that reduce kernel launch overhead during the forward and backward passes.

## Summary

- **Unsloth** provides a drop-in replacement for standard TRL workflows that cuts VRAM usage by approximately 60% and doubles training speed through optimized kernels and quantization.

- The `huggingface/skills` repository packages Unsloth as a reusable skill in `skills/hugging-face-model-trainer/`, with the main entry point at [`scripts/unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/scripts/unsloth_sft_example.py).

- **Key implementation details** include `FastLanguageModel.from_pretrained` for optimized model loading, `FastLanguageModel.get_peft_model` for simplified LoRA configuration, and `use_gradient_checkpointing="unsloth"` for memory-efficient training.

- The CLI supports local execution via UV, cloud training via `hf jobs`, and integration with Trackio for real-time monitoring.

## Frequently Asked Questions

### How much VRAM does Unsloth actually save compared to standard TRL?

According to the source documentation in [`skills/hugging-face-model-trainer/references/unsloth.md`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/references/unsloth.md), Unsloth reduces VRAM consumption by approximately 60% compared to standard TRL workflows. This reduction comes from 4-bit quantization during model loading, 8-bit AdamW optimizer states (`optim="adamw_8bit"`), and Unsloth's custom gradient checkpointing implementation that minimizes memory allocation during the backward pass.

### Can I use Unsloth with vision-language models (VLMs)?

Yes, Unsloth supports vision-language models through `FastVisionModel` and `UnslothVisionDataCollator`, as documented in the reference files. While the primary [`unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/unsloth_sft_example.py) script focuses on text-only models like `LiquidAI/LFM2.5-1.2B-Instruct`, the underlying Unsloth library provides optimized kernels for multimodal training that offer the same VRAM reductions and speed improvements available for language-only models.

### What is the default model used in the Hugging Face skills trainer?

The [`scripts/unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/scripts/unsloth_sft_example.py) script uses `LiquidAI/LFM2.5-1.2B-Instruct` as the default base model when no `--model` argument is specified. This 1.2B parameter model serves as an efficient default for testing and development, though the script supports any Hugging Face model compatible with Unsloth's `FastLanguageModel.from_pretrained` method, including larger models like Llama-2-7b or Mistral-7B when sufficient VRAM is available.

### How do I merge LoRA weights after training with Unsloth?

After training completes, you can merge LoRA adapters into the base model using the `--merge-model` flag when running [`unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/unsloth_sft_example.py), which calls `model.push_to_hub_merged` to create a full 16-bit merged checkpoint. Alternatively, in Python code, you can load the saved adapter and call the merge method before pushing to the Hub, resulting in a single model file that requires no PEFT dependencies during inference, though this produces a larger artifact than the adapter-only approach.