QLoRA Fine-Tuning with Unsloth: December 2025 Install Guide

The #1 mistake people make with Unsloth in 2026? Copying the install snippet from a 2024 Colab tutorial. That command – pip install "unsloth[colab-new] @ git+..." with pinned xformers<0.0.27 – fights the modern unsloth_zoo resolver and throws a wall of dependency errors. The GitHub issue tracker is full of people stuck on exactly that (GitHub issues #1743, #1136, #1150 all show the same dependency resolver failures with the extras-based install).

What actually works in the December 2025 release cycle: fewer flags, no extras, let Unsloth resolve its own stack. This guide covers the current install path for QLoRA fine-tuning, compares Docker vs pip with a real decision table, and walks through three errors with fixes pulled from the tracker. No dataset code, no training loop rehash.

What Unsloth actually does for QLoRA

QLoRA – from Dettmers et al. (2023) – finetunes a 65B model on a single 48GB GPU by backpropagating through a frozen, 4-bit quantized model into Low Rank Adapters. The technique introduces 4-bit NormalFloat (NF4), double quantization, and paged optimizers. That’s the algorithm. Unsloth is the runtime that makes it fast.

The December 2025 release ships 3x faster training and 30% less VRAM via new Triton kernels, padding-free and packing. 500K context training on a single 80GB GPU is now possible – and for Llama 3.3 70B specifically, Unsloth pushes 89K context (that’s 13x more than HuggingFace + FlashAttention 2). Llama 3.1 8B gets 342K, surpassing its own native 128K limit.

Think of it this way: QLoRA is the math, Unsloth is the engine tuning. You need both, but if the engine misfires at install time, none of the math matters. That’s the only thing this guide is about.

System requirements (December 2025 build)

The docs bury this: float16 mixed precision breaks on Tesla T4, RTX 2080, and even A100 during Gemma 3 finetuning (per March 2025 release notes). Unsloth auto-picks float32 as fallback – which costs VRAM. Plan for it, especially on free Colab. Bfloat16 is fine on Ampere and newer.

Docker or pip?

Docker: zero setup, curated dependency stack, safest if you’ve fought CUDA before. The catch: ~7 GB image pull and you’re pinned to whatever versions the maintainers chose.

pip: full control, works inside existing venvs, easier to pin exotic combos. But you own the resolution when it breaks. And it will break if you use the wrong command – more on that below.

On Blackwell/RTX 50 or a fresh cloud VM, use Docker. Already have a working PyTorch+CUDA environment? Use pip. Don’t mix approaches on the same box.

Install via Docker (recommended for fresh machines)

One image tag. Turns out unsloth/unsloth is Unsloth’s only Docker image – for Blackwell and RTX 50-series GPUs, you use this same image, no separate CUDA-versioned tag needed. Anyone telling you to pick a specific CUDA image is reading outdated instructions.

# NVIDIA Container Toolkit required first (Linux)
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

# Pull the image (~7 GB compressed)
docker pull unsloth/unsloth

# Run with Jupyter + mounted work dir
docker run -d -e JUPYTER_PASSWORD="mypassword" 
 -p 8888:8888 
 -v $(pwd)/work:/workspace/work 
 --gpus all 
 unsloth/unsloth

Open http://localhost:8888, enter your password. The image includes pre-installed Unsloth with all dependencies already resolved – that’s the main reason to choose this path.

Install via pip (if you already have PyTorch working)

Forget the old [colab-new] extras. The November 2025 release notes specify one command for both fresh installs and upgrades:

# Fresh install or upgrade - same command
pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

# Moving to newer PyTorch? Use this instead
pip install --upgrade unsloth unsloth_zoo

The --no-deps flag. Not decorative. Drop it and pip re-resolves torch, xformers, bitsandbytes, and vllm against each other – on any non-trivial environment, that fails. Issue #1136 is the canonical example of that resolution blowing up.

Quick check: After installing, run python -m xformers.info before touching any training code. Torch mismatch shows in 2 seconds instead of 20 minutes into a run.

Is pip ever the wrong choice even with a working environment? If your team members run different OS versions or CUDA drivers – probably. The Docker image eliminates that entire class of “works on my machine” failures. Something to weigh before committing to either path long-term.

First-time config: minimum viable QLoRA

Smallest script that proves the install works. Loads a 4-bit model, attaches LoRA adapters – no training loop, just a sanity check:

from unsloth import FastLanguageModel
import torch

model, tokenizer = FastLanguageModel.from_pretrained(
 model_name = "unsloth/llama-3.2-3b-bnb-4bit",
 max_seq_length = 2048,
 dtype = None, # auto: bfloat16 on Ampere+, float32 fallback on T4
 load_in_4bit = True # this is the Q in QLoRA
)

model = FastLanguageModel.get_peft_model(
 model,
 r = 16,
 target_modules = ["q_proj","k_proj","v_proj","o_proj",
 "gate_proj","up_proj","down_proj"],
 lora_alpha = 16,
 use_gradient_checkpointing = "unsloth",
)
print("ready:", model.num_parameters(only_trainable=True), "trainable params")

That prints a number in the low millions and no CUDA errors? Deployed. Done.

Common install errors and what actually fixes them

Error 1: Could not find a version that satisfies bitsandbytes>=0.43.3

CUDA 11.8 or an old conda env – the newer bitsandbytes wheels simply aren’t published for that platform (GitHub issues #1743 and #1476 on the Unsloth tracker). Fix: upgrade to CUDA 12.1+ or switch to the Docker path. There’s no pip workaround that doesn’t introduce other breakage.

Error 2: xFormers can't load C++/CUDA extensions

GitHub issue #879. Root cause: xFormers was built against a different torch version than the one you have – a missing libcudart or straight-up version mismatch. Fix: use the December 2025 command with --no-deps so Unsloth’s pinned versions win. Don’t manually pin xformers yourself.

Error 3: ModuleNotFoundError: No module named 'unsloth' after install

Sneaky one. Install completes cleanly. Then FastLanguageModel import raises ModuleNotFoundError. Almost always means the install ran in a different Python than the notebook kernel. Check: import sys; print(sys.executable) in the notebook – match that Python to the pip you ran.

Upgrading and cleaning up

Same one-liner as install. --force-reinstall handles the upgrade. For Docker, docker pull unsloth/unsloth and re-run.

Uninstall:

# pip path
pip uninstall unsloth unsloth_zoo bitsandbytes xformers -y

# Docker path
docker stop $(docker ps -q --filter ancestor=unsloth/unsloth)
docker rmi unsloth/unsloth

One thing people miss: the Hugging Face model cache. Base models are large – 4-bit quantized versions are smaller but still substantial – and they sit in ~/.cache/huggingface/hub until you manually delete them. Check that directory before assuming a clean uninstall freed your disk.

FAQ

Do I need to install bitsandbytes separately?

No. It’s a transitive dependency of unsloth_zoo. Only touch it manually if you’re building a locked requirements file.

Can I run Unsloth on an AMD or Apple Silicon GPU?

AMD on Linux – there’s preliminary support, but the December 2025 release docs don’t specify which ROCm versions are tested (as of this writing, treat it as experimental). Apple Silicon is a clearer answer: Unsloth Studio runs for chat and MLX inference on M-series Macs, but QLoRA training is CUDA-only in the December 2025 release. If you’re on an M-series Mac and want to fine-tune, use a cloud GPU. Your laptop will not thank you for trying.

Why does my Gemma 3 training loss explode on Colab?

Float16 breaks Gemma 3 gradients – not just on T4, but on A100 too (confirmed in Unsloth’s March 2025 release notes). Unsloth auto-selects float32 as a workaround. That costs VRAM. If you hit OOM after the auto-fallback kicks in, reduce batch size or max_seq_length. Bfloat16 works correctly on Ampere and newer – if you have an A100 and want to use it, set dtype=torch.bfloat16 explicitly rather than relying on the auto-detect.

Pull the image or run the pip one-liner, load unsloth/llama-3.2-3b-bnb-4bit, confirm the trainable-params count prints. If it does, the QLoRA rig is deployed and ready for a real dataset.