Environment:Unslothai Unsloth Python Transformers

Knowledge Sources	Unsloth pyproject.toml
Domains	Infrastructure, NLP, Deep_Learning
Last Updated	2026-02-07 09:00 GMT

Overview

Python 3.9-3.13 environment with PyTorch 2.1+, Transformers 4.51.3+, TRL 0.18.2+, PEFT 0.18.0+, and Accelerate 0.34.1+ for Unsloth text model training and inference.

Description

This environment provides the core Python software stack required for all Unsloth text-based workflows including supervised fine-tuning, response masking, model saving, merging, and Hub upload. It centers on the HuggingFace ecosystem (transformers, trl, peft, accelerate, datasets) with strict version constraints to avoid known compatibility issues. The transformers package has numerous excluded versions due to regressions in specific releases. Model-specific features (Gemma 2, Qwen 3, Falcon H1, etc.) require progressively higher minimum transformers versions.

Usage

Use this environment for all Unsloth text-based workflows: QLoRA SFT fine-tuning, response masking, chat template application, model merging and saving (SafeTensors), and HuggingFace Hub upload. This is the base prerequisite for every Unsloth operation; the CUDA and vLLM environments extend it with GPU-specific requirements.

System Requirements

Category	Requirement	Notes
OS	Linux (recommended), Windows via WSL2	macOS not officially supported for training
Python	3.9 - 3.13	`requires-python = ">=3.9,<3.14"` in pyproject.toml
Hardware	CPU minimum; GPU recommended	GPU-accelerated environments extend this base
Disk	10GB+	For model weights, tokenizer files, and cached datasets

Dependencies

System Packages

`python` >= 3.9, < 3.14
`git` (for model/dataset downloads from HuggingFace Hub)
`protobuf` (Python implementation forced via env var)

Python Packages

`torch` >= 2.1.0 (PyTorch; exact CUDA-matched wheel required for GPU)
`transformers` >= 4.51.3, with exclusions: !=4.52.0, !=4.52.1, !=4.52.2, !=4.52.3, !=4.53.0, !=4.54.0, !=4.55.0, !=4.55.1, !=4.57.0, !=4.57.4, !=4.57.5, <=4.57.6
`trl` >= 0.18.2, !=0.19.0, <=0.24.0
`peft` >= 0.18.0, !=0.11.0
`accelerate` >= 0.34.1
`datasets` >= 3.4.1, !=4.0.*, !=4.1.0, <4.4.0
`huggingface_hub` >= 0.34.0
`sentencepiece` >= 0.2.0
`unsloth_zoo` >= 2026.2.1
`psutil` (for memory management during model merging)
`safetensors` (for SafeTensors serialization)
`tyro` (for CLI interface)
`packaging` (for version comparison logic)

Credentials

The following environment variables may be required:

`HF_TOKEN`: HuggingFace API token (Read access for gated models, Write access for Hub upload).

Quick Install

# Install core Unsloth with all dependencies
pip install unsloth

# Or install individual packages
pip install "torch>=2.1.0" "transformers>=4.51.3,<=4.57.6" "trl>=0.18.2,<=0.24.0" \
    "peft>=0.18.0" "accelerate>=0.34.1" "datasets>=3.4.1,<4.4.0" \
    "huggingface_hub>=0.34.0" "sentencepiece>=0.2.0" "unsloth_zoo>=2026.2.1" \
    psutil safetensors tyro packaging

Code Evidence

Transformers feature gating from `models/loader.py:68-79`:

transformers_version = Version(transformers_version)
SUPPORTS_FOURBIT = transformers_version >= Version("4.37")
SUPPORTS_GEMMA   = transformers_version >= Version("4.38")
SUPPORTS_GEMMA2  = transformers_version >= Version("4.42")
SUPPORTS_LLAMA31 = transformers_version >= Version("4.43.2")
SUPPORTS_LLAMA32 = transformers_version > Version("4.45.0")
SUPPORTS_GRANITE = transformers_version >= Version("4.46.0")
SUPPORTS_QWEN3   = transformers_version >= Version("4.50.3")
SUPPORTS_FALCON_H1 = transformers_version >= Version("4.53.0")

Unsloth Zoo version check from `__init__.py:80-87`:

try:
    unsloth_zoo_version = importlib_version("unsloth_zoo")
    if Version(unsloth_zoo_version) < Version("2026.2.1"):
        print("Unsloth: Please update Unsloth and Unsloth-Zoo to the latest version!...")
except PackageNotFoundError:
    raise ImportError("Unsloth: Please install unsloth_zoo via `pip install unsloth_zoo` then retry!")

PyTorch import check from `__init__.py:105-113`:

try:
    import torch
except ModuleNotFoundError:
    raise ImportError(
        "Unsloth: Pytorch is not installed. Go to https://pytorch.org/.\n"
        "We have some installation instructions on our Github page."
    )

Datasets version exclusion from `import_fixes.py:448-460`:

def patch_datasets():
    datasets_version = Version(importlib_version("datasets"))
    if (datasets_version <= Version("4.5.0")) and (datasets_version >= Version("4.4.0")):
        raise NotImplementedError(
            f"#### Unsloth: Using `datasets = {str(datasets_version)}` will cause recursion errors.\n"
            "Please downgrade datasets to `datasets==4.3.0"
        )

Common Errors

Error Message	Cause	Solution
`ImportError: Please install unsloth_zoo`	unsloth_zoo package missing	`pip install unsloth_zoo>=2026.2.1`
`ImportError: Pytorch is not installed`	torch not installed	Visit https://pytorch.org/ for install instructions
`RuntimeError: Pixtral only works on transformers >= 4.49.0`	transformers too old for model	`pip install transformers>=4.49.0`
`RuntimeError: Gemma 3 only works on transformers >= 4.50.0`	transformers too old for Gemma 3	`pip install transformers>=4.50.0`
`NotImplementedError: datasets will cause recursion errors`	datasets 4.4.0-4.5.0 has a bug	`pip install datasets==4.3.0`
`Please update Unsloth and Unsloth-Zoo to the latest version`	unsloth_zoo version too old	`pip install --upgrade unsloth_zoo`

Compatibility Notes

Model-specific transformers versions: Different model architectures require different minimum transformers versions. Qwen 3 requires >= 4.50.3, Falcon H1 requires >= 4.53.0, Gemma 3N requires >= 4.53.0.
TRL version ceiling: TRL is capped at <= 0.24.0. Newer TRL versions may introduce breaking API changes in trainer classes.
PEFT exclusion: PEFT 0.11.0 is excluded due to compatibility issues.
Datasets exclusion: Datasets versions 4.4.0-4.5.0 cause recursion errors and are explicitly blocked.
Protobuf: Unsloth forces `PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python` environment variable to avoid protobuf C++ extension issues.
Torchvision compatibility: Unsloth checks torch-torchvision version compatibility at startup and warns if mismatched (can be skipped via `UNSLOTH_SKIP_TORCHVISION_CHECK=1`).

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment