Transformers

Overview

The Hugging Face Transformers library provides access to thousands of pre-trained models for tasks across NLP, computer vision, audio, and multimodal domains. Use this skill to load models, perform inference, and fine-tune on custom data.

Installation

Targets Transformers 5.18.0, verified against its released source on 2026-10-01. Native CPU checks use Python 3.11, Torch 2.14.1, Datasets 5.0.1, Accelerate 1.15.0, PEFT 0.21.2, and Hub 1.33.0. The Torch extra requires Torch >=2.5. Install in a dedicated environment:

uv venv --python 3.11 .venv-transformers
uv pip install --python .venv-transformers/bin/python "transformers[torch]==5.18.0" "torch==2.14.1" "huggingface-hub==1.33.0" "datasets==5.0.1" "accelerate==1.15.0" "peft==0.21.2"

Use .venv-transformers/Scripts/python.exe on Windows. Select an appropriate Torch build for the target hardware before installation. Hub 2.1.1 is newer, but Datasets 5.0.1 requires Hub <2; upgrading every package independently makes this training stack unsatisfiable. The separate esm SDK currently requires Transformers <5 and belongs in another environment.

Optional dependencies (install only for the selected workflow): Pillow 12.3.0 for images; torchvision matched to Torch and timm 1.0.30 for models that require them; librosa 1.0.0 and soundfile 0.14.0 for audio preprocessing (librosa requires Python >=3.12); FFmpeg for encoded audio file inputs; pytesseract plus Tesseract for OCR document pipelines; bitsandbytes 0.50.2 for supported quantization backends. See model loading before choosing precision or quantization.

Verification used tiny random models, synthetic input, and local save/reload only. Hub pretrained examples throughout this skill are illustrative: public checkpoint metadata and configurations were reviewed, but no weights or datasets were downloaded and no hosted inference or uploads were run. Optional export/distributed/hardware paths are source-checked, not end-to-end tested. See review evidence.

Check your version:

import transformers
print(transformers.__version__)

Authentication

Many models on the Hugging Face Hub are gated or private. Authenticate before loading them.

Recommended: CLI login (uses $HF_TOKEN_PATH, defaulting to $HF_HOME/token, normally ~/.cache/huggingface/token):

hf auth login

Python:

from huggingface_hub import login
login()  # Interactive prompt; do not hardcode tokens in scripts

Servers / CI: set HF_TOKEN in the environment (never commit tokens to git or shell profiles):

export HF_TOKEN="..."  # Read token from a secret manager, not source code

Get tokens at: https://huggingface.co/settings/tokens

Security: Never paste tokens into notebooks, repos, or shared configs. Prefer hf auth login over exporting tokens in .bashrc or .zshrc.

Use the narrowest token scope that works: read for private or gated model downloads, write only for uploads. If a long-running environment should not send the stored token on every Hub request, set HF_HUB_DISABLE_IMPLICIT_TOKEN=1 and pass a token only where authentication is required.

Transformers v5

Transformers v5 is PyTorch-only (TensorFlow and JAX backends were removed). For upgrades from v4, see the v5 migration guide. Transformers 5.18.0 accepts Hub >=1.31,<3; preserve the tighter constraint of Datasets when training.

Gated or custom architectures: accept the model license on the Hub, then load with trust_remote_code=True only when required custom code has been reviewed; pin its full immutable commit with revision (and code_revision for a separate code repository). Gating and custom code are independent: a gated built-in architecture does not require remote code.

Cache location: set HF_HOME for all Hugging Face caches, or HF_HUB_CACHE just for Hub files. Use HF_HUB_OFFLINE=1 only after required model snapshots are already cached.

Quick Start

Use the Pipeline API for fast inference without manual configuration:

from transformers import pipeline

# Text generation (prefer max_new_tokens for causal LMs)
generator = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B")
result = generator("The future of AI is", max_new_tokens=50)

# Text classification

…