Registry / ai-ml / unsloth

unsloth

JSON →
library2026.8.22pypypi✓ verified 24d ago

Unsloth is a library that enables 2-5X faster training, reinforcement learning, and finetuning of large language models (LLMs) on consumer GPUs, often reducing VRAM usage. As of version 2026.4.4, it continues to provide significant optimizations for Hugging Face Transformers models. Releases follow a calendar-based versioning scheme, indicating frequent updates.

pip install "unsloth[cu121]" --upgrade
INSTALL
IMPORT
SIG · UNSLOTH
U
unsloth
ai-mlpythonv2026.8.22
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2024.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ timeout
✕ timeout
py 3.11
1/3 runs
✕ timeout
py 3.12
1/3 runs
✕ timeout
py 3.13
1/3 runs
✕ timeout
py 3.9
✕ timeout
✕ timeout
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FastLanguageModel
from unsloth import FastLanguageModel
PatchModel
from unsloth import FastLanguageModel, PatchModel
PatchModel is often imported alongside FastLanguageModel for convenience.

This quickstart demonstrates how to load a pre-trained LLM using Unsloth's `FastLanguageModel.from_pretrained` with 4-bit quantization and then prepare it for PEFT (LoRA) finetuning using `get_peft_model`. It sets up the model for efficient training on a GPU.

from unsloth import FastLanguageModel import torch # 1. Load a pre-trained model and tokenizer max_seq_length = 2048 # Max sequence length for your model dtype = None # None for auto detection (bfloat16 preferred, float16 as fallback) load_in_4bit = True # Use 4-bit quantization model, tokenizer = FastLanguageModel.from_pretrained( model_name = "unsloth/mistral-7b-instruct-v0.2-bnb-4bit", # or "mistralai/Mistral-7B-Instruct-v0.2" max_seq_length = max_seq_length, dtype = dtype, load_in_4bit = load_in_4bit, ) # 2. Prepare the model for training (add LoRA adapters) model = FastLanguageModel.get_peft_model( model, r = 16, # LoRA attention dimension target_modules = [ "q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj", ], lora_alpha = 16, # Alpha for LoRA scaling lora_dropout = 0.05, # Dropout for LoRA layers bias = "none", # Only under the LoRA layers use_gradient_checkpointing = "current-device", random_state = 3407, use_rslora = False, loftq_config = None, ) # 3. Define a simple dataset (for demonstration) # In a real scenario, you would load your actual dataset here # from datasets import Dataset # dataset = Dataset.from_dict({"text": ["...", "..."]}) print("Model and tokenizer loaded and prepared for finetuning!") print(f"Using dtype: {model.dtype}, Quantization: {model.quantization_method}") # Further steps would involve data preparation and using Hugging Face Trainer
Debug
Known issues
gotchaUnsloth performance critically depends on matching your CUDA toolkit version (if using NVIDIA GPUs) with the correct `[cuXXX]` installation extra (e.g., `[cu121]` for CUDA 12.1). Mismatching can lead to significant performance degradation or runtime errors.
fix
Always install Unsloth with the specific CUDA extra that matches your PyTorch/system CUDA installation (e.g., `pip install "unsloth[cu121]"`). Verify your `torch.version.cuda`.
affects: All versions
gotchaUnsloth is primarily designed and optimized for GPU acceleration. While it might run on a CPU, performance will be severely degraded and practically unusable for meaningful LLM finetuning. Ensure you have a compatible NVIDIA GPU with sufficient VRAM.
fix
Ensure your environment has a compatible NVIDIA GPU and that PyTorch is configured to use it (e.g., `torch.cuda.is_available()` should return `True`).
affects: All versions
gotchaUnsloth often relies on specific versions of `transformers` and `peft` libraries for optimal compatibility and performance. New releases of these dependencies might introduce breaking changes or require updates to Unsloth itself.
fix
Check the Unsloth GitHub README or release notes for recommended `transformers` and `peft` versions. Regularly update Unsloth and its dependencies, or pin versions to known-working configurations.
affects: All versions
breakingThe arguments and default values for `FastLanguageModel.from_pretrained` and `FastLanguageModel.get_peft_model` can change between major Unsloth releases, especially concerning quantization, LoRA configuration, and gradient checkpointing.
fix
Refer to the latest Unsloth documentation or GitHub README for the correct API signatures and recommended parameters when upgrading. Pay attention to changes in `dtype`, `load_in_4bit`, `r`, `target_modules`, and `use_gradient_checkpointing`.
affects: Likely between calendar-year updates (e.g., 202X.Y.Z)
Upgrade
Version history
2026.8.22latest on PyPI · released Aug 27, 2026
Audit
Dependencies
pythonrequiredRequired Python version range for unsloth.
torchrequiredCore deep learning framework. Specific CUDA versions are often required and should match unsloth's installation.
transformersrequiredUnsloth integrates deeply with Hugging Face Transformers for model loading and training.
Agent activity
41 hits · last 30 days
node
36
Perplexity
1
OpenAI (training)
1
Resources
unsloth — pip install unsloth · libregistry