Fastest LoRA Training: Unsloth December 2025 Install Guide

The #1 mistake with fastest LoRA training setups isn’t picking the wrong hyperparameters – it’s installing Unsloth on top of a mismatched PyTorch/CUDA/xformers stack. You get a green install log, then a cryptic runtime crash the moment you call FastLanguageModel.from_pretrained(). Reverse the problem: pin your CUDA and PyTorch versions first, then let Unsloth install into that pinned environment.

This guide covers the December-2025 release, which brings a 3x speedup and 30% less VRAM via new Triton kernels, padding-free attention, and packing. If you’re on RTX 50-series or DGX Spark hardware, jump straight to the Blackwell section – the standard install path won’t work for you.

What Unsloth actually is (30 seconds)

Monkey-patching at load time. Per the Hugging Face Transformers integration docs, FastLanguageModel.from_pretrained uses AutoConfig normally – but before the base model loads, it swaps out the attention class, decoder layer, and rotary embedding implementation with Unsloth’s hand-written Triton kernels. Same model. Faster math.

December-2025 pushed the ceiling further: 500K context training and RL on a single 80GB GPU (per the official release notes). Free under Apache 2.0, with a paid Pro tier for enterprise support.

Here’s what’s worth sitting with for a moment: most “fastest fine-tuning” tools optimize the obvious stuff – batch size, mixed precision. Unsloth goes one layer deeper and rewrites how the GPU computes attention itself. That’s why the VRAM numbers look implausible until you actually run it.

System requirements

CUDA Capability 7.0 is the hard floor. Below that, nothing loads. Per the unsloth-zoo PyPI page, that covers V100, T4, RTX 20/30/40-series, A100, H100, and L40. GTX 1070/1080 technically qualify but are slow enough to be impractical.

Python 3.13 is the current upper bound as of December 2025 (per the GitHub README). Pascal-only rigs – P100, GTX 10-series without Volta – are dead ends. The 8GB VRAM minimum for 7B QLoRA is real; 16GB gives you room to iterate without OOM restarts.

Install: the command that actually works

Fresh conda environment. Skipping this is where most horror stories start – an old xformers wheel lingers in a shared env, nothing aligns, and the error message points you nowhere useful.

# 1. Clean environment
conda create -n unsloth python=3.11 -y
conda activate unsloth

# 2. Install PyTorch FIRST, pinned to your CUDA
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 3. Install Unsloth (December-2025 stable path)
pip install unsloth

# 4. Verify GPU is visible
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# 5. Verify Unsloth imports cleanly
python -c "from unsloth import FastLanguageModel; print('ok')"

Step 4 prints False? Stop. Everything below this line breaks. The fix is almost always a driver/PyTorch CUDA mismatch – nvidia-smi shows the driver’s max supported CUDA version; your PyTorch wheel must be equal to or lower than that.

Docker: skip dependency hell entirely

The official image ships a working, pre-tested stack. Pull the current tag (PyTorch 2.9.0, CUDA 12.8, per the GitHub Container Registry):

docker pull ghcr.io/unslothai/unsloth:2026.2.1-pt2.9.0-cu12.8-fixed-gguf-conversion
docker run --gpus all -it -p 8888:8888 
 ghcr.io/unslothai/unsloth:2026.2.1-pt2.9.0-cu12.8-fixed-gguf-conversion

Host driver doesn’t support CUDA 12.8? Pick an older tag from the registry listing – the tag name encodes the exact PyTorch and CUDA versions, so you can match to your driver without guessing.

First-time configuration: minimal LoRA training script

Ten training steps. That’s all you need to confirm Unsloth is running kernels on GPU and not silently falling back to CPU. Watch nvidia-smi -l 1 in a second terminal – VRAM should climb past 2-3GB within 30 seconds of trainer.train():

from unsloth import FastLanguageModel
from datasets import load_dataset
from trl import SFTTrainer, SFTConfig

model, tokenizer = FastLanguageModel.from_pretrained(
 model_name = "unsloth/Llama-3.2-1B-Instruct",
 max_seq_length = 2048,
 load_in_4bit = True,
)

model = FastLanguageModel.get_peft_model(
 model,
 r = 16,
 lora_alpha = 16,
 target_modules = ["q_proj","k_proj","v_proj","o_proj",
 "gate_proj","up_proj","down_proj"],
 use_gradient_checkpointing = "unsloth",
)

ds = load_dataset("trl-lib/Capybara", split="train[:500]")
trainer = SFTTrainer(model=model, tokenizer=tokenizer,
 train_dataset=ds,
 args=SFTConfig(output_dir="out", max_steps=10,
 dataset_num_proc=1))
trainer.train()

dataset_num_proc=1 – on Windows, community users report this prevents a crashing issue in SFTConfig. On Linux you can remove it. If VRAM never rises above ~500MB during training, bitsandbytes fell back to its CPU-only build. Fix that first (see error #1 below) before debugging anything else.

Four install errors you’ll actually hit

Not a complete list. A specific one. Every other Unsloth install failure is usually a variation of these four.

1. “bitsandbytes was compiled without GPU support”
Turns out this warning is easy to miss – the import doesn’t crash, it just quietly loads libbitsandbytes_cpu.so. 8-bit optimizers, 8-bit matrix multiplication, and GPU quantization are all gone (GitHub issue #221). Fix: pip uninstall bitsandbytes && pip install bitsandbytes --no-cache-dir. Still failing? Your CUDA runtime isn’t on the library path – set LD_LIBRARY_PATH to include your CUDA lib64 directory.

2. “xFormers was built for PyTorch X.Y with CUDA Z (you have …)”
Happens after any PyTorch upgrade. xFormers can’t load its C++/CUDA extensions because the build target changed (GitHub issue #1026 documents the exact error string). Memory-efficient attention is disabled. You’ll get correct output but at roughly half the expected speed – don’t ignore this. Fix: reinstall xformers matching your current torch version, or pin torch back to what xformers expects.

3. RTX 5090 / Blackwell: “sm_120 is not compatible”
Blackwell cards report CUDA capability sm_120. Standard PyTorch stable wheels top out at sm_90. GitHub issue #1679 tracks this. Fix path:

pip install --pre torch torchvision torchaudio 
 --index-url https://download.pytorch.org/whl/nightly/cu128
# then rebuild bitsandbytes and xformers from source

Or use the December-2025 Docker image, which bakes in cu12.8 and skips the compilation step entirely.

4. Dependency resolver stuck for 10+ minutes
pip is trying to satisfy conflicting version constraints across unsloth, xformers, bitsandbytes, and torch simultaneously. The fix: install with --no-deps for auxiliary packages and pin torch first, exactly as shown in step 2 of the install block above. This is why step order matters.

The gpt-oss VRAM cliff (this one actually matters)

Any other training library needs a minimum of 65GB VRAM to train gpt-oss-20b. Unsloth needs 14GB. Per the official gpt-oss docs, the gap comes from a specific architectural quirk: gpt-oss stores weights in MXFP4 format as nn.Parameter objects rather than nn.Linear layers. Every other library has to upcast those weights to bf16 before training – that upcasting alone inflates VRAM by up to 300% and slows training down proportionally.

Unsloth patches the loader to handle MXFP4 natively. The difference isn’t a preference – it’s the difference between running on a consumer card and renting a multi-GPU node. If gpt-oss is your target model, there’s no real alternative here.

Upgrade and uninstall

Official upgrade command (from November-2025 release notes) – the --no-deps flag is deliberate:

pip install --upgrade --force-reinstall --no-cache-dir --no-deps 
 unsloth unsloth_zoo

Without --no-deps, pip re-resolves the entire dependency tree and can drag in a newer torch that breaks your xformers build. If you specifically want PyTorch 2.9, drop the flag and let it resolve – but do it in a fresh env.

Uninstall:

pip uninstall unsloth unsloth_zoo -y
conda deactivate
conda env remove -n unsloth

Your ~/.cache/huggingface keeps model weights around – delete that separately if you want the disk space back.

Multi-GPU: honest expectations

Unsloth is a single-GPU tool. The December-2025 release added preliminary DDP support – explicitly flagged in the release notes as not representative of the official multi-GPU release coming in early 2026. Eight H100s and a deadline? Use DeepSpeed or FSDP today. One 4090 or one A100? Unsloth wins on every metric that matters for that hardware.

FAQ

Does Unsloth work on AMD or Intel GPUs?

Yes, via ROCm for AMD and a separate install path for Intel – see the AMD guide. Performance parity with NVIDIA isn’t guaranteed.

Can I run this on a free Google Colab T4?

Yes – and it’s the fastest way to validate your training script before committing to real hardware. T4 has 15GB VRAM and CUDA capability 7.5 (as of early 2026; this may have changed), both above the minimums. Use load_in_4bit=True and stick to models ≤8B. One catch: Colab sessions die at 12 hours max. Push checkpoints to Hugging Face Hub or Google Drive during training, not after – if the session drops, anything not pushed is gone.

Is Unsloth actually 3x faster, or is that marketing?

Both, depending on your baseline. The December-2025 release notes claim 3x versus a standard Hugging Face Trainer run with no flash attention. Against a well-tuned FA2 + gradient checkpointing baseline, expect 1.5x-2x with 40-70% less VRAM. The VRAM reduction is actually the more reliable win – it’s consistent across configurations in a way the speed figure isn’t. The 3x headline assumes a specific (favorable) comparison.

Next step: spin up a conda environment with the exact commands above, run the 10-step SFTTrainer script on Llama-3.2-1B, and watch nvidia-smi. Under two minutes and VRAM climbing? Your install is production-ready. Error? Match the string to section 6 and fix it before touching a larger model.