transformers

library5.16.1pypypi✓ verified 14d ago

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.

ai-ml llm-agents data

pip install transformers[torch]

github ↗package ↗

INSTALL

IMPORT

SIG · TRANSFORMERS

transformers

ai-mlpythonv5.16.1

Install

44.2s avg

Import

10725ms

Disk

690MB

Pass rate

3/ 10

Env Coverage3 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.16.1 · 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

3/5 runs

✓ 47.6s

py 3.11

3/5 runs

✓ 42.62s

py 3.12

3/5 runs

✓ 42.44s

py 3.13

3/5 runs

4/5 runs

py 3.9

3/5 runs

690MB installed

● package 690MB

Code

Verified usage

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

pipeline

✓ from transformers import pipeline

✗ import transformers; transformers.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

✗ from transformers import AutoFeatureExtractor

AutoFeatureExtractor is removed in v5. Use AutoImageProcessor for vision models.

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" )

Debug

Known issues

breakingv5 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.

affects: v5.0+

breakingload_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))

affects: v5.0+

breakingAutoFeatureExtractor 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.

affects: v5.0+

breakingtokenizer.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')

affects: v5.0+

breakingTRANSFORMERS_CACHE environment variable removed in v5. Cache location now controlled by HF_HOME.

fix

Replace: export TRANSFORMERS_CACHE=/path with: export HF_HOME=/path

affects: v5.0+

breakingPython 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.

affects: v5.0+

gotchapip 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.

affects: all

gotchaModels 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.

affects: all

gotchadevice_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.

affects: all

breakingBuilding `tokenizers` (a core dependency of `transformers`) from source often fails on musl-based Linux distributions (like Alpine) due to missing C toolchain libraries (e.g., `libgcc_s.so.1`) or Rust compilation issues. This occurs when compatible pre-built wheels for the specific Python version and musl architecture are not available, forcing a source build.

fix

Ensure your Alpine environment has `build-base` and `rust` packages installed (e.g., `apk add build-base rust`). For newer Python versions or if issues persist, consider using official Python images based on glibc (e.g., `python:3.x-slim-bullseye` instead of `python:3.x-alpine`) or explicitly pinning `tokenizers` to a version with a compatible musl wheel if available.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'transformers.modeling_tf_utils'

Transformers v5 removed all TensorFlow and Flax backend support, including the `modeling_tf_utils` module, making it a PyTorch-only library.

fix

Migrate your code to use PyTorch-compatible classes and functions, or downgrade `transformers` to a v4 version (e.g., `pip install transformers==4.x.x`) if TensorFlow support is essential.

ImportError: transformers requires Python 3.10 or higher.

Transformers v5 explicitly requires Python version 3.10 or newer, and your current environment is running an older Python version.

fix

Upgrade your Python installation to version 3.10 or higher, or install `transformers` v4 (e.g., `pip install transformers==4.x.x`) if you need to use an older Python version.

ValueError: Loading a model with custom code requires passing `trust_remote_code=True`.

You are attempting to load a model or tokenizer from the Hugging Face Hub that includes custom Python code, which `transformers` blocks by default for security reasons.

fix

Add `trust_remote_code=True` to your `from_pretrained()` call (e.g., `AutoModel.from_pretrained('org/model', trust_remote_code=True)`), but only if you understand and trust the source of the custom code.

OSError: Can't load weights for 'MODEL_NAME'. If you were trying to load it from 'https://huggingface.co/...' or from local files

The specified model or its configuration/weights could not be found or accessed on the Hugging Face Hub or locally, possibly due to a typo, network issues, or a private model without proper authentication.

fix

Double-check the model name for typos, ensure you have an an active internet connection, and if it's a private model, ensure you are logged in (`huggingface-cli login`) or provide a valid authentication token.

Upgrade

Version history

5.16.1latest on PyPI · released Aug 26, 2026

Audit

Dependencies

torchrequiredRequired for v5. TensorFlow and Flax/JAX support removed in v5. PyTorch 2.4+ recommended.

huggingface_hubrequiredRequired. Used for model downloading, caching, and Hub interactions.

tokenizersrequiredRequired. Rust-based fast tokenizer backend. v5 consolidates all tokenizers to use this or sentencepiece.

accelerateoptionalRequired for device_map='auto', multi-GPU, and most modern inference patterns.

Agent activity

165 hits · last 30 days

node

148