transformers

Transformers is a library from Hugging Face that acts as a shared model-definition layer for machine learning across text, computer vision, audio, video, and multimodal tasks, for both inference and training. Instead of every training framework and inference engine defining models differently, Transformers centralizes the model definition so it stays compatible across the ecosystem: tools like Axolotl, Unsloth, DeepSpeed, FSDP, and PyTorch-Lightning for training, and vLLM, SGLang, and TGI for inference, all work with model definitions from this library. It's aimed at researchers, engineers, and developers who want to use or fine-tune pretrained models without writing model architectures from scratch.

Key features

• Unified Pipeline API: a single high-level interface for text, audio, vision, and multimodal tasks that handles preprocessing and returns ready-to-use output.
• Access to 1M+ checkpoints: direct access to over a million pretrained model checkpoints hosted on the Hugging Face Hub.
• Framework interoperability: move a single model between PyTorch, JAX, and TensorFlow, and pick the framework that fits training, evaluation, or production separately.
• Minimal abstraction: model code lives in individual files without extra shared abstractions layered on top, so you can read and modify one model's implementation without tracing through unrelated code.
• Command-line chat: chat with a supported model directly from the terminal via the transformers chat command, once transformers serve is running.
• Broad modality coverage: example models are documented for speech recognition, image classification, visual question answering, document understanding, and text generation, among others.
• Wide language documentation: the README and core docs are translated into over a dozen languages, including Chinese, Korean, Spanish, Japanese, French, and Arabic.

Ideal use cases

Transformers is a strong fit for loading and running pretrained models for inference, whether that's text generation, classification, image or audio tasks, or multimodal use cases, without training a model from scratch. It's also well suited to fine-tuning existing checkpoints for a specific task, since the library shares model definitions with major training frameworks, letting you reuse the same definition from experimentation through to deployment. Researchers who need to inspect or modify a model's internals benefit from the intentionally unabstracted, per-model code files, and the project highlights 100 real projects built on top of it in its awesome-transformers list as evidence of how broadly it's used in practice.

It's not designed as a general building-block toolkit for assembling arbitrary neural network architectures. If you need a generic training loop for custom models outside the library's scope, the project points to Accelerate instead. The bundled example scripts are meant as references, not production-ready code, so expect to adapt them for your specific use case rather than running them unmodified against your own data.

Transformers also publishes a citable paper describing the library's design, which matters for academic or research use where citing the tooling is expected. Since a single model definition targets a low barrier to entry with just a few user-facing abstraction classes to learn, engineers moving between very different model types, say from an audio model to a vision-language model, don't have to relearn a new API surface each time.

Installation

Transformers requires Python 3.10+ and PyTorch 2.4+. Create a virtual environment first, using either venv or uv:

# venv
python -m venv .my-env
source .my-env/bin/activate

# uv
uv venv .my-env
source .my-env/bin/activate

Then install the package:

pip install "transformers[torch]"

To install from source for the latest changes:

git clone https://github.com/huggingface/transformers.git
cd transformers
pip install '.[torch]'

A minimal usage example with the Pipeline API:

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
pipeline("the secret to baking a really good cake is ")