Hugging Face Transformers

5.2.0 · active · verified Sat Feb 28

The central model-definition framework for state-of-the-art ML models across text, vision, audio, video, and multimodal tasks. Provides pretrained model weights, tokenizers, pipelines, and training APIs. Interfaces with PyTorch (primary), with 400+ model architectures and 750k+ checkpoints on the Hub. MAJOR VERSION NOTE: v5 released late 2025 — first major release in 5 years. v5 is PyTorch-only (TensorFlow/Flax/JAX removed). pip install transformers installs v5 as of Feb 2026. v4 was the last stable version before this; v4.57.x is the last v4 release. Requires Python 3.10+ in v5.

Warnings

breaking v5 drops TensorFlow and Flax/JAX support entirely. TFAutoModel, FlaxAutoModel, and all TF/Flax model classes are removed. pip install transformers now installs v5 — existing code using TF/Flax will break on import.
Fix: Migrate to PyTorch. If TF/Flax is required, pin: pip install 'transformers<5'. Last v4 release: 4.57.3.
breaking load_in_4bit and load_in_8bit as direct kwargs to from_pretrained() are removed in v5. Must use BitsAndBytesConfig.
Fix: from transformers import BitsAndBytesConfig; model = AutoModel.from_pretrained(id, quantization_config=BitsAndBytesConfig(load_in_4bit=True))
breaking AutoFeatureExtractor removed in v5. Use AutoImageProcessor. Fast/slow image processor distinction also eliminated — only 'fast' variants (requires torchvision) remain.
Fix: Replace AutoFeatureExtractor with AutoImageProcessor. Install torchvision if missing.
breaking tokenizer.encode_plus() deprecated in v5. tokenization_utils and tokenization_utils_fast module paths removed and redirected.
Fix: Replace encode_plus() with direct tokenizer() call: tokenizer(text, truncation=True, padding='max_length', max_length=128, return_tensors='pt')
breaking TRANSFORMERS_CACHE environment variable removed in v5. Cache location now controlled by HF_HOME.
Fix: Replace: export TRANSFORMERS_CACHE=/path with: export HF_HOME=/path
breaking Python 3.10+ required in v5. Python 3.9 and below are not supported.
Fix: Upgrade to Python 3.10+. Or pin transformers<5 for Python 3.9.
gotcha pip install transformers (no extras) installs the package but does NOT install PyTorch. Importing any model then raises 'No module named torch'. This is a constant source of confusion for new users.
Fix: Always install with extras: pip install transformers[torch]. Or install torch separately first.
gotcha Models are downloaded to ~/.cache/huggingface/hub on first from_pretrained() call. Large models (7B+) can be tens of GB. In CI or containers with limited disk, this causes silent failures or disk full errors.
Fix: Set HF_HOME to a volume with sufficient space. Pre-download models using snapshot_download() or huggingface-cli download.
gotcha device_map='auto' requires accelerate to be installed. Without it, from_pretrained(..., device_map='auto') raises ImportError. Not installed by default with transformers[torch].
Fix: pip install accelerate alongside transformers.

Install

pip install transformers[torch] With PyTorch (recommended)
pip install transformers Core only (no backend — add torch/tf/jax separately)
pip install transformers[vision] With vision dependencies (Pillow, torchvision)
pip install transformers[audio] With audio dependencies (librosa, soundfile)
pip install 'transformers<5' Pin to v4.x (last v4: 4.57.3) if v5 breaking changes are blocking

Imports

pipeline
```
from transformers import pipeline
```
pipeline() is the recommended high-level entry point. Handles model + tokenizer loading and pre/post processing.
AutoModelForCausalLM
```
from transformers import AutoModelForCausalLM, AutoTokenizer
```
Always use Auto classes (AutoModel, AutoTokenizer, AutoConfig) over model-specific classes for forward compatibility.
AutoImageProcessor (v5)
```
from transformers import AutoImageProcessor
```
AutoFeatureExtractor is removed in v5. Use AutoImageProcessor for vision models.

Quickstart

pipeline() handles everything automatically. For quantization in v5, use BitsAndBytesConfig — passing load_in_4bit=True directly to from_pretrained() is removed.

from transformers import pipeline

# Text generation
generator = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct")
result = generator("The future of AI is", max_new_tokens=50)
print(result[0]['generated_text'])

# Embeddings / feature extraction
from transformers import AutoTokenizer, AutoModel
import torch

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased")

inputs = tokenizer("Hello, world!", return_tensors="pt")
with torch.no_grad():
    outputs = model(**inputs)
    embeddings = outputs.last_hidden_state[:, 0, :]  # [CLS] token
print(embeddings.shape)  # torch.Size([1, 768])

# Quantized inference (v5 pattern)
from transformers import AutoModelForCausalLM, BitsAndBytesConfig
quant_config = BitsAndBytesConfig(load_in_4bit=True)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-3B",
    quantization_config=quant_config,
    device_map="auto"
)

view raw JSON →