timm (PyTorch Image Models) is an open‑source deep‑learning library built on PyTorch, providing a unified interface for a vast collection of computer‑vision model architectures, pre‑trained weights, and training utilities. Maintained by Ross Wightman, timm streamlines research and application development by offering hundreds of pre‑configured models (e.g., ResNet, EfficientNet, Vision Transformers) with consistent APIs, data‑augmentation pipelines, and optimizers. It is widely used in academic papers and production systems for tasks such as image classification, feature extraction, and fine‑tuning.
1.1 History and Motivation
timm was created by Ross Wightman in 2018 as a personal repository to centralize and standardize the growing number of PyTorch model implementations. At the time, each model architecture often required bespoke code, making it difficult to compare methods or reuse components. The library was initially named “pytorch‐image‐models” and later shortened to “timm”. Its primary motivation was to provide a clean, consistent interface for loading and training models, while also distributing high‑quality pre‑trained weights. Over time, the project grew through community contributions and became a de facto standard in the computer‑vision research ecosystem.
1.2 Core Design Philosophy
timm follows three core principles: simplicity, flexibility, and reproducibility. Simplicity is achieved through a unified model creation API—all models can be loaded with a single timm.create_model() function. Flexibility is maintained by exposing the underlying PyTorch modules, allowing users to modify architecture parameters (e.g., number of classes, input channels) without forking the codebase. Reproducibility is ensured by providing well‑documented training scripts, default hyperparameters, and consistent weight download paths.
1.3 Relationship to PyTorch Ecosystem
timm sits alongside other PyTorch vision tools such as torchvision and the Hugging Face transformers library. While torchvision offers a smaller, curated set of models with official PyTorch support, timm includes a much larger collection—often containing the latest research architectures—and provides more advanced training utilities (e.g., custom augmentations, optimizers, schedulers). timm models are also integrated into Hugging Face’s transformers for image‑text tasks, and many third‑party frameworks (e.g., Detectron2, Lightning) directly rely on timm as a model backend.
2.1 System Requirements
timm requires Python 3.8 or later and PyTorch 1.8 or later. It is compatible with Linux, macOS, and Windows operating systems. A CUDA‑enabled GPU is recommended for training but not required for inference. Disk space for pre‑trained weight downloads varies by model; typical sizes range from 10 MB to several hundred megabytes.
2.2 Installation via pip
The simplest installation method uses pip:
pip install timmThis command installs the latest stable version from PyPI, along with all necessary dependencies (e.g., torch, torchvision, Pillow). To obtain a specific version, specify the version number:
pip install timm==0.9.122.3 Installation from Source
To install the development version or contribute to the library, clone the official repository and run:
git clone https://github.com/huggingface/pytorch-image-models.git
cd pytorch-image-models
pip install -e .The -e flag installs the library in editable mode, allowing changes to the source code to take effect immediately. Users should also install the development dependencies if they intend to run tests or create pull requests.
3.1 Supported Architectures
timm hosts over 300 model variants, covering convolutional, transformer, and hybrid architectures. Each architecture is implemented as a PyTorch nn.Module and can be instantiated with various configurations (e.g., different depths, channel widths, activation functions).
3.1.1 Convolutional Neural Networks
The classic CNN families include ResNet, DenseNet, VGG, and Inception. timm provides many variants of these—for example, ResNet‑18, ResNet‑50, ResNet‑101, as well as custom versions (ResNeXt, Wide ResNet). More recent convolutional designs such as ConvNeXt, EfficientNet‑V1/V2, and RegNet are also available.
3.1.2 Vision Transformers and Hybrid Models
timm supports an extensive range of Vision Transformer (ViT) models, including the original ViT, DeiT, Swin Transformer, and CaiT. Hybrid architectures that combine CNNs with transformers—such as CoAtNet, LeViT, and MaxViT—are also included. Implementation details follow the official releases, often with additional efficiency improvements (e.g., fused attention kernels).
3.1.3 EfficientNet and Mobile Networks
The library covers EfficientNet‑B0 through B8, MobileNet‑V2/V3, and MnasNet. These models are optimized for speed and parameter count, making them popular for edge deployment. timm also provides pretrained weights for many of these on ImageNet‑1K and ImageNet‑21K.
3.2 Pre‑trained Weights
Pre‑trained weights are automatically downloaded from a central repository (primarily hosted on Hugging Face Hub) the first time a model is loaded. The weights are stored in a local cache (~/.cache/torch/hub/checkpoints/ by default) to avoid repeated downloads.
3.2.1 Model Naming Conventions
Each model variant has a unique string identifier, typically following the pattern [architecture]_[variant]. For example, resnet50, efficientnet_b0, vit_base_patch16_224. Additional suffixes indicate dataset or training regime, such as _in21k for ImageNet‑21k pre‑trained or _dino for self‑supervised DINO weights.
3.2.2 Weight Sources and Licenses
Most weights originate from the original authors’ training (e.g., official TensorFlow Model Garden, timm’s own training runs, or third‑party reproducible experiments). Each model entry documents the source and license. Common licenses include Apache 2.0, MIT, and BSD‑3. Users are responsible for verifying the license of any model used in commercial projects.
4.1 Loading a Pre‑trained Model
To load a pre‑trained model for inference, use the timm.create_model() function with the model name and the pretrained=True argument:
import timm
model = timm.create_model('resnet50', pretrained=True)
model.eval()The model is returned as a standard PyTorch module, ready for forward passes. If no pre‑trained weights are available for a given variant, setting pretrained=True raises a warning.
4.2 Inference and Feature Extraction
To perform inference on an image, preprocess it using timm.data.transforms_factory.create_transform() which applies the correct normalization statistics for the model. For feature extraction, the model can be wrapped with a timm.models.features module to access intermediate layer outputs:
import torch
from timm.models import create_model
model = create_model('resnet50', pretrained=True, features_only=True)
input_tensor = torch.randn(1, 3, 224, 224)
features = model(input_tensor) # returns list of feature maps at specified output stages4.3 Model Configuration and Customization
Models can be customized by passing arguments to create_model. Common parameters include:
num_classes(default 1000): output size for the classification head.in_chans(default 3): input channels.drop_rate,drop_path_rate: stochastic depth or dropout ratios.
For example, to create a ResNet‑50 with 10 output classes and 1 input channel (e.g., grayscale images):
model = timm.create_model('resnet50', pretrained=True, num_classes=10, in_chans=1)5.1 Data Pipeline and Augmentation
timm provides a comprehensive data pipeline built on torch.utils.data.DataLoader and custom dataset classes (e.g., timm.data.ImageDataset). The library emphasizes strong augmentation strategies to improve generalization.
5.1.1 Built‑in Transformations
The timm.data.transforms_factory module includes standard transformations like random resized crops, horizontal flips, color jittering, and normalization. Users can compose their own transforms or use the pre‑configured pipeline generated by create_transform().
5.1.2 RandAugment and AutoAugment
timm implements several modern augmentation policies:
- RandAugment: randomly selects a subset of augmentation operations (e.g., rotation, shear, contrast) with a fixed magnitude.
- AutoAugment: learns an optimal augmentation policy from the data (ImageNet‑based policies are provided for common architectures).
- AugMix: mixes multiple augmented versions of an image to improve robustness.
These are enabled through the aug_cfg parameter in the training configuration.
5.2 Training Scripts and Configuration
The library ships with a rich training script (train.py) that accepts command‑line arguments or YAML configuration files. Key features include automatic checkpointing, learning rate scheduling (cosine, step, plateau), and optimizer choices (SGD, AdamW, LAMB).
5.2.1 Hyperparameter Tuning
timm’s training script exposes over 100 hyperparameters, including batch size, learning rate, weight decay, label smoothing, and mixup/ cutmix ratios. Users can easily override defaults via command line or configuration files. The repository also provides “model results” tables that document optimal hyperparameters for many architectures.
5.2.2 Distributed Training Support
Distributed training is supported via PyTorch’s DistributedDataParallel (DDP). To launch training on multiple GPUs, use torchrun or python -m torch.distributed.run. The script automatically handles gradient synchronization and learning rate scaling (linear scaling rule). Single‑GPU training is the default when no distributed launcher is used.
5.3 Evaluation and Metrics
Evaluation is performed using the validate.py script, which computes top‑1 and top‑5 accuracy on a validation set. timm also includes tools for per‑class accuracy, confusion matrices, and recall/precision. For custom tasks, users can write their own evaluation loop using the model’s forward method.
6.1 Model Ensembling
timm provides utilities to combine multiple models for inference, either by averaging their logits or by stacking predictions. The timm.utils.model_ema module also supports Exponential Moving Average (EMA) models, which can be used as a test‑time ensemble without extra computational cost.
6.2 Gradient Accumulation
Gradient accumulation allows training with large virtual batch sizes by accumulating gradients over several forward/backward passes before stepping the optimizer. timm’s training script includes a --grad-accum-steps argument, enabling the use of a small physical batch size while simulating a larger effective batch.
6.3 Mixed Precision (AMP)
Automatic Mixed Precision (AMP) training is supported natively via PyTorch’s torch.cuda.amp. timm’s training script includes the --amp flag, which enables dynamic loss scaling and float16 computation for faster training with lower memory usage. Models that use batch normalization automatically adjust statistics when AMP is enabled.
7.1 Integrations with Hugging Face
In 2022, timm became part of the Hugging Face ecosystem, with its models available through the transformers library. Users can load timm models via AutoModelForImageClassification.from_pretrained("timm/resnet50.a1_in1k"). The integration also provides access to timm’s pre‑trained weights through the Hugging Face Hub.
7.2 Contribution Guidelines
Contributions are welcome via pull requests to the pytorch-image-models repository. Guidelines include:
- Follow the existing code style (PEP 8 + type hints).
- Add tests for new models or features.
- Document model sources and licenses.
- Use the provided pre‑commit hooks for linting.
The maintainers encourage adding new architectures that have demonstrated strong performance or that fill a gap in the model zoo.
7.3 Versioning and Release Cycle
timm follows semantic versioning (MAJOR.MINOR.PATCH). Releases occur irregularly but typically every 1–3 months, aligning with significant new model additions or breaking changes. The current stable version is 1.0.x (as of early 2025). Users can track upcoming releases via GitHub milestones. The library has no fixed deprecation policy; deprecated features are announced in release notes and removed after one major version cycle.