# huggingface/transformers architecture

> Architecture diagram of the GitHub repository huggingface/transformers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huggingface/transformers
- Repository: https://github.com/huggingface/transformers
- Video tour (about a minute): https://gitdiagram.com/huggingface/transformers/video

## Overview

Transformers is a model-definition library for inference and training across text, vision, audio, video, and multimodal tasks. A typical user workflow is to select a pretrained model, prepare inputs through a pipeline or modality processor, run model inference or generation, and receive task-specific outputs. The repository also provides model/configuration and tokenizer support, distributed execution, export backends, and a CLI serving interface. Arrows follow README-described behavior or references and calls visible in sampled files; unsampled subsystem links are omitted where their wiring is not established.

Main entry points: [`src/transformers/modeling_utils.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py) (Pretrained Models), [`src/transformers/pipelines/__init__.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/pipelines/__init__.py) (Task Pipelines), [`src/transformers/processing_utils.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/processing_utils.py) (Multimodal Processors), [`src/transformers/cli/transformers.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/cli/transformers.py) (Transformers CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_pipeline["Task Pipelines<br/>[__init__.py]"]
  node_cli["Transformers CLI<br/>[transformers.py]"]
  node_serving["Serving Server<br/>[server.py]"]
  node_manager["Model Manager<br/>[model_manager.py]"]
end

subgraph group_input["Input Preparation"]
  node_processor["Multimodal Processors"]
  node_tokenizer["Tokenizers"]
  node_features["Feature Extraction"]
end

subgraph group_models["Models and Generation"]
  node_model["Pretrained Models<br/>[modeling_utils.py]"]
  node_architecture["Model Architectures"]
  node_auto["Auto Model Selection<br/>[modeling_auto.py]"]
  node_generation["Text Generation<br/>[utils.py]"]
  node_continuous["Continuous Batching<br/>[continuous_api.py]"]
  node_outputs["Model Outputs"]
end

subgraph group_runtime["Execution and Export"]
  node_distributed["Distributed Execution"]
  node_integrations["Framework Integrations"]
  node_export["Model Export"]
end

subgraph group_shared["Shared Model Assets"]
  node_config["Model Configuration"]
  node_cache[("Generation Cache<br/>[cache_utils.py]")]
  node_hub["Hugging Face Hub"]
end

node_user(("User"))

node_user -->|"submits task"| node_pipeline
node_pipeline -->|"preprocesses input"| node_processor
node_pipeline -->|"runs inference"| node_model
node_pipeline -->|"returns results"| node_outputs
node_user -->|"runs command"| node_cli
node_cli -->|"registers serve"| node_serving
node_serving -->|"dispatches model requests"| node_manager
node_manager -->|"selects model class"| node_auto
node_auto -.->|"resolves architecture"| node_architecture
node_model -->|"loads configuration"| node_config
node_architecture -.->|"implements model definitions"| node_model
node_model -->|"produces outputs"| node_outputs
node_model -->|"supports generation"| node_generation
node_generation -->|"uses decoding cache"| node_cache
node_processor -.->|"uses tokenization"| node_tokenizer
node_processor -.->|"prepares modality features"| node_features
node_continuous -->|"manages cache"| node_cache
node_model -->|"supports distributed loading"| node_distributed
node_model -.->|"uses optional backends"| node_integrations
node_user -->|"selects checkpoint"| node_hub
node_model -->|"loads pretrained checkpoint"| node_hub
node_model -.->|"can export model"| node_export

click node_pipeline "https://github.com/huggingface/transformers/blob/main/src/transformers/pipelines/__init__.py"
click node_cli "https://github.com/huggingface/transformers/blob/main/src/transformers/cli/transformers.py"
click node_serving "https://github.com/huggingface/transformers/blob/main/src/transformers/cli/serving/server.py"
click node_manager "https://github.com/huggingface/transformers/blob/main/src/transformers/cli/serving/model_manager.py"
click node_processor "https://github.com/huggingface/transformers/blob/main/src/transformers/processing_utils.py"
click node_tokenizer "https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_base.py"
click node_features "https://github.com/huggingface/transformers/blob/main/src/transformers/feature_extraction_utils.py"
click node_config "https://github.com/huggingface/transformers/blob/main/src/transformers/configuration_utils.py"
click node_model "https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py"
click node_architecture "https://github.com/huggingface/transformers/tree/main/src/transformers/models"
click node_auto "https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/modeling_auto.py"
click node_generation "https://github.com/huggingface/transformers/blob/main/src/transformers/generation/utils.py"
click node_continuous "https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py"
click node_cache "https://github.com/huggingface/transformers/blob/main/src/transformers/cache_utils.py"
click node_outputs "https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_outputs.py"
click node_distributed "https://github.com/huggingface/transformers/tree/main/src/transformers/distributed"
click node_integrations "https://github.com/huggingface/transformers/tree/main/src/transformers/integrations"
click node_export "https://github.com/huggingface/transformers/tree/main/src/transformers/exporters"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pipeline,node_cli,node_serving,node_manager,node_user toneBlue
class node_processor,node_tokenizer,node_features toneAmber
class node_model,node_architecture,node_auto,node_generation,node_continuous,node_outputs toneMint
class node_distributed,node_integrations,node_export toneRose
class node_config,node_cache,node_hub toneIndigo
```

## Components

### User Interfaces

- [Task Pipelines](https://github.com/huggingface/transformers/blob/main/src/transformers/pipelines/__init__.py): `src/transformers/pipelines/__init__.py`
- [Transformers CLI](https://github.com/huggingface/transformers/blob/main/src/transformers/cli/transformers.py): `src/transformers/cli/transformers.py`
- [Serving Server](https://github.com/huggingface/transformers/blob/main/src/transformers/cli/serving/server.py): `src/transformers/cli/serving/server.py`
- [Model Manager](https://github.com/huggingface/transformers/blob/main/src/transformers/cli/serving/model_manager.py): `src/transformers/cli/serving/model_manager.py`

### Input Preparation

- [Multimodal Processors](https://github.com/huggingface/transformers/blob/main/src/transformers/processing_utils.py): `src/transformers/processing_utils.py`
- [Tokenizers](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_base.py): `src/transformers/tokenization_utils_base.py`
- [Feature Extraction](https://github.com/huggingface/transformers/blob/main/src/transformers/feature_extraction_utils.py): `src/transformers/feature_extraction_utils.py`

### Models and Generation

- [Pretrained Models](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py): `src/transformers/modeling_utils.py`
- [Model Architectures](https://github.com/huggingface/transformers/tree/main/src/transformers/models): `src/transformers/models`
- [Auto Model Selection](https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/modeling_auto.py): `src/transformers/models/auto/modeling_auto.py`
- [Text Generation](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/utils.py): `src/transformers/generation/utils.py`
- [Continuous Batching](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py): `src/transformers/generation/continuous_batching/continuous_api.py`
- [Model Outputs](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_outputs.py): `src/transformers/modeling_outputs.py`

### Execution and Export

- [Distributed Execution](https://github.com/huggingface/transformers/tree/main/src/transformers/distributed): `src/transformers/distributed`
- [Framework Integrations](https://github.com/huggingface/transformers/tree/main/src/transformers/integrations): `src/transformers/integrations`
- [Model Export](https://github.com/huggingface/transformers/tree/main/src/transformers/exporters): `src/transformers/exporters`

### Shared Model Assets

- [Model Configuration](https://github.com/huggingface/transformers/blob/main/src/transformers/configuration_utils.py): `src/transformers/configuration_utils.py`
- [Generation Cache](https://github.com/huggingface/transformers/blob/main/src/transformers/cache_utils.py): `src/transformers/cache_utils.py`
- **Hugging Face Hub**

### Other components

- **User**

## Connections

- User → Task Pipelines: submits task (evidence: `README.md`)
- Task Pipelines → Multimodal Processors: preprocesses input (evidence: `README.md`)
- Task Pipelines → Pretrained Models: runs inference (evidence: `README.md`)
- Task Pipelines → Model Outputs: returns results (evidence: `README.md`)
- User → Transformers CLI: runs command (evidence: `README.md`)
- Transformers CLI → Serving Server: registers serve (evidence: `src/transformers/cli/transformers.py`)
- Serving Server → Model Manager: dispatches model requests (evidence: `src/transformers/cli/serving/server.py`)
- Model Manager → Auto Model Selection: selects model class (evidence: `src/transformers/cli/serving/model_manager.py`)
- Auto Model Selection → Model Architectures: resolves architecture (evidence: `src/transformers/models/rag/modeling_rag.py`)
- Pretrained Models → Model Configuration: loads configuration (evidence: `src/transformers/modeling_utils.py`)
- Model Architectures → Pretrained Models: implements model definitions (evidence: `src/transformers/models/rag/modeling_rag.py`)
- Pretrained Models → Model Outputs: produces outputs (evidence: `README.md`)
- Pretrained Models → Text Generation: supports generation (evidence: `README.md`)
- Text Generation → Generation Cache: uses decoding cache
- Multimodal Processors → Tokenizers: uses tokenization (evidence: `src/transformers/processing_utils.py`)
- Multimodal Processors → Feature Extraction: prepares modality features (evidence: `src/transformers/processing_utils.py`)
- Continuous Batching → Generation Cache: manages cache
- Pretrained Models → Distributed Execution: supports distributed loading (evidence: `src/transformers/modeling_utils.py`)
- Pretrained Models → Framework Integrations: uses optional backends (evidence: `src/transformers/modeling_utils.py`)
- User → Hugging Face Hub: selects checkpoint (evidence: `README.md`)
- Pretrained Models → Hugging Face Hub: loads pretrained checkpoint (evidence: `README.md`)
- Pretrained Models → Model Export: can export model
