Definition and purpose
Torchvision is an open‑source Python library that provides essential tools for computer vision tasks within the PyTorch ecosystem. It offers a curated collection of commonly used datasets, pre‑built model architectures, and image transformation utilities. The library is designed to streamline the development, training, and evaluation of vision models, allowing researchers and practitioners to focus on high‑level logic rather than low‑level data handling and model implementation details.
Relationship with PyTorch
Torchvision is maintained by the PyTorch team under the same governance as PyTorch itself. It is distributed as a separate package but is tightly integrated with PyTorch’s tensor and autograd system. Many torchvision modules, such as datasets and transforms, output PyTorch tensors, and the model architectures are built using torch.nn. The library is versioned in parallel with PyTorch, and compatibility is documented for each release.
Typical workflows using torchvision
A common workflow involves loading a standard dataset (e.g., CIFAR‑10) with pre‑applied transforms, instantiating a pre‑trained classification model, and fine‑tuning it for a custom task. Another typical use is building a data pipeline that reads images, applies augmentations, and feeds batches to a model defined in PyTorch. Torchvision also serves as a reference implementation for reproducing baseline results in computer vision research.
Early releases (2017–2019)
Torchvision was first released in 2017 alongside PyTorch 0.2.0. Early versions included a handful of datasets (MNIST, CIFAR‑10, CIFAR‑100, ImageNet loading), basic transforms (resize, crop, normalize), and a few model architectures (AlexNet, VGG, ResNet). The library adopted a functional API for transforms and provided datasets.ImageFolder for custom folder‑based datasets.
Major milestones (2020–2024)
In 2020, torchvision introduced the torchvision.transforms.v2 module (later becoming the default interface) with improved data consistency and support for arbitrary structured outputs. The torchvision.datasets module expanded to include video datasets (Kinetics, UCF101) and detection datasets (COCO, VOC). Model zoos grew with EfficientNet, ConvNeXt, and detection architectures (Faster R‑CNN, Mask R‑CNN, RetinaNet). Version 0.12 (2022) added the first vision transformer models (ViT, DeiT). By 2024, torchvision had reached version 0.16+, with support for video transformers, advanced augmentations (AutoAugment, RandAugment), and the torchvision.io module for image/video I/O.
Current version and support policy
The latest stable release (as of early 2025) is version 0.19. Torchvision follows PyTorch’s release cadence: a minor version is released every three months, with backward‑compatibility promises for public APIs. Older versions receive security and critical bug fixes for a limited window. The project is hosted on GitHub under the pytorch/vision repository and accepts community contributions.
Standard classification datasets
ImageNet
ImageNet is a large‑scale dataset of over 14 million labeled images spanning 1,000 object classes. Torchvision provides a datasets.ImageNet class that downloads the ILSVRC2012 subset (training and validation splits) from official sources, requiring manual registration. The class supports common preprocessing, including resizing, cropping, and normalization to match standard evaluation protocols.
CIFAR‑10 and CIFAR‑100
CIFAR‑10 consists of 60,000 32×32 color images in 10 classes (6,000 per class), with 50,000 training and 10,000 test images. CIFAR‑100 is similar but has 100 classes (600 images each). Torchvision’s datasets.CIFAR10 and datasets.CIFAR100 automatically download the data from the University of Toronto servers and provide the standard train/test split as a PyTorch dataset object.
Object detection and segmentation datasets
COCO
The Common Objects in Context (COCO) dataset contains over 330,000 images with annotations for object detection, segmentation, and captioning. Torchvision’s datasets.CocoDetection loads images and annotation files (JSON format) and returns images with target dictionaries containing bounding boxes, masks, and category labels. The library supports the 2014 and 2017 splits.
Pascal VOC
Pascal VOC provides images annotated with 20 object classes for detection and segmentation. Torchvision includes datasets.VOCDetection and datasets.VOCSegmentation, which download the VOC 2007 and VOC 2012 datasets. The detection dataset returns bounding boxes and class labels; the segmentation dataset returns per‑pixel class masks.
Video datasets
Kinetics
Kinetics is a large‑scale human action recognition dataset containing short YouTube clips covering 400 or 600 action classes (depending on version). Torchvision’s datasets.Kinetics downloads the clips (via pre‑processed frame archives) and provides a video_clips attribute that returns a list of contiguous clip tensors. The class handles sampling, temporal jittering, and frame‑based transforms.
UCF101
UCF101 is an action recognition dataset with 101 categories and 13,320 clips sourced from YouTube. The datasets.UCF101 class in torchvision loads the dataset from the provided frame‑level archive (split files) and returns sequences of frames as tensors. It supports standard evaluation splits (training and testing).
Image transforms
Resize, crop, and flip
Common spatial augmentations include transforms.Resize (to a fixed size or shortest‑edge), transforms.RandomCrop, transforms.CenterCrop, and transforms.RandomHorizontalFlip. These transforms operate on PIL Images or tensors and support interpolation modes and padding options.
Color jitter and normalization
transforms.ColorJitter randomly adjusts brightness, contrast, saturation, and hue. transforms.Normalize standardizes image tensors with per‑channel mean and standard deviation, typical for pre‑trained model inputs. Torchvision also provides transforms.Grayscale and transforms.RandomGrayscale.
Tensor transforms
ToTensor and ConvertImageDtype
transforms.ToTensor converts a PIL Image or numpy array (H×W×C, uint8) to a float tensor (C×H×W) with pixel values scaled to [0,1]. transforms.ConvertImageDtype casts tensor dtype (e.g., from uint8 to float32) without scaling, preserving the original range. These are useful when working with different input formats.
Composing transformations
Compose class
transforms.Compose accepts a list of transforms and applies them sequentially. It is the traditional way to build a data preprocessing pipeline. For example: transforms.Compose([Resize(256), RandomCrop(224), ToTensor(), Normalize(mean, std)]).
AutoAugment and RandAugment
transforms.AutoAugment applies a learned augmentation policy (e.g., for ImageNet or CIFAR‑10) that selects operations like shear, rotate, and color adjustments with variable magnitudes. transforms.RandAugment uses a simplified parameterization (N operations, M magnitude) and is effective for training robust models. Both are available as callable transforms in torchvision.
Classification models
AlexNet and VGG
AlexNet is a pioneering 8‑layer convolutional network that won the 2012 ImageNet competition. Torchvision provides torchvision.models.alexnet with pre‑trained weights. VGG (VGG‑11, VGG‑13, VGG‑16, VGG‑19) features deeper architectures with small 3×3 convolutions and is available in both batch‑normalized and non‑normalized variants.
ResNet and ResNeXt
ResNet introduces residual connections for training very deep networks (18, 34, 50, 101, 152 layers). Torchvision includes standard ResNet variants as well as ResNeXt, which replaces single‑path convolutions with grouped convolutions (cardinality). All models come with ImageNet‑pre‑trained weights.
EfficientNet and ConvNeXt
EfficientNet uses compound scaling (depth, width, resolution) to achieve state‑of‑the‑art accuracy with fewer parameters. Torchvision provides EfficientNet‑B0 through B7. ConvNeXt modernizes the ResNet design with inverted bottlenecks, larger kernels, and LayerNorm, achieving transformer‑level performance on ImageNet.
Object detection and segmentation models
Faster R‑CNN
Faster R‑CNN is a two‑stage detector: a Region Proposal Network (RPN) generates candidate boxes, and a Fast R‑CNN head classifies and refines them. Torchvision’s torchvision.models.detection.fasterrcnn_resnet50_fpn uses a Feature Pyramid Network (FPN) backbone and is pre‑trained on COCO.
Mask R‑CNN
Mask R‑CNN extends Faster R‑CNN by adding a mask prediction branch for instance segmentation. Torchvision provides maskrcnn_resnet50_fpn with COCO pre‑training, outputting bounding boxes, class labels, and binary masks.
RetinaNet and SSD
RetinaNet is a single‑stage detector using focal loss to handle class imbalance; torchvision includes retinanet_resnet50_fpn. SSD (Single Shot MultiBox Detector) is available via ssd300_vgg16 or ssdlite320_mobilenet_v3_large, optimized for speed.
Video models
R3D and MC3
R3D (ResNet 3D) extends the ResNet architecture to 3D convolutions for spatiotemporal features. MC3 (Mixed Convolution 3D) combines 2D and 3D convolutions for efficiency. Both are available in torchvision.models.video with Kinetics pre‑training.
SlowFast
The SlowFast model uses a slow, high‑resolution pathway and a fast, low‑resolution pathway to capture motion cues. Torchvision provides slowfast_r50 pre‑trained on Kinetics, supporting video classification tasks.
Model weights and pretraining
ImageNet‑pretrained weights
All classification models come with weights trained on ImageNet‑1K (1000 classes). Detection and segmentation models are pre‑trained on COCO (detection/segmentation) or ImageNet (backbone). Video models are pre‑trained on Kinetics‑400 or Kinetics‑600.
Weight enumeration and loading conventions
Torchvision uses Enum‑based weight constants (e.g., ResNet50_Weights.IMAGENET1K_V1). To load a pre‑trained model: model = resnet50(weights=ResNet50_Weights.IMAGENET1K_V2). The weights parameter can be set to 'DEFAULT' for the best available version. Each weight enum documents accuracy metrics and preprocessing requirements.
Image I/O
read_image and write_png
torchvision.io.read_image(path) reads an image file (JPEG, PNG) and returns a uint8 tensor of shape (C×H×W). torchvision.io.write_png(tensor, path) writes a tensor to a PNG file. These functions use libpng/libjpeg for I/O and are GPU‑compatible on CUDA systems.
Visualization tools
make_grid and save_image
torchvision.utils.make_grid(tensor, nrow=8) arranges a batch of images into a grid (used to display multiple samples). torchvision.utils.save_image(tensor, path) saves the grid or single image to disk. Both normalize pixel values internally and support padding.
Bounding box and mask utilities
torchvision.ops provides operations like nms (non‑maximum suppression), box_iou, roi_align, and ps_roi_align. torchvision.utils.draw_bounding_boxes annotates images with bounding boxes, and draw_segmentation_masks overlays class‑wise masks. These utilities facilitate post‑processing of detection and segmentation outputs.
System requirements
Torchvision requires Python 3.8 or later and a compatible PyTorch installation. For GPU support, a CUDA‑capable GPU and NVIDIA drivers (version 11.x or newer) are recommended. The library supports Linux, macOS, and Windows.
Installation via pip and conda
The recommended installation uses conda: conda install pytorch torchvision -c pytorch. With pip: pip install torch torchvision. Additionally, pip supports nightly builds: pip install --pre torch torchvision --index-url https://download.pytorch.org/whl/nightly/cu118. Users can select CUDA version (cu118, cu121, or CPU‑only) by choosing the appropriate index URL.
GPU support and CUDA dependencies
When installed with CUDA support, torchvision automatically detects the GPU device and uses CUDA kernels for transforms, I/O, and model inference. Some operations (e.g., roi_align, nms) include CUDA‑specific implementations for faster execution. CPU‑only installs are also available for systems without GPUs, with reduced performance.
Loading a dataset and applying transforms
import torchvision
from torchvision import transforms, datasets
transform = transforms.Compose([
transforms.Resize(256),
transforms.RandomCrop(224),
transforms.ToTensor(),
transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
])
train_set = datasets.CIFAR10(root='./data', train=True, download=True, transform=transform)
train_loader = torch.utils.data.DataLoader(train_set, batch_size=64, shuffle=True)Fine‑tuning a pretrained model
import torchvision.models as models
model = models.resnet50(weights='DEFAULT')
num_features = model.fc.in_features
model.fc = torch.nn.Linear(num_features, 10) # 10 classes for CIFAR‑10
# Freeze backbone (optional)
for param in model.parameters():
param.requires_grad = False
for param in model.fc.parameters():
param.requires_grad = True
# Train model using standard PyTorch loopCustom dataset and transform pipeline
from torchvision.datasets import ImageFolder
from torchvision import transforms
custom_transform = transforms.Compose([
transforms.Resize(128),
transforms.RandomRotation(15),
transforms.ToTensor()
])
dataset = ImageFolder(root='./my_images', transform=custom_transform)Official documentation and tutorials
The torchvision documentation is hosted at pytorch.org/vision. It includes API references, example notebooks, and guides for using datasets, transforms, and models. Tutorials cover fine‑tuning, detection pipelines, and video processing. The official PyTorch forums and GitHub discussions provide community support.
Third‑party wrappers and integrations
Torchvision is integrated into higher‑level libraries such as Lightning Flash, Hugging Face datasets, and Albumentations (via adapter transforms). Some cloud platforms (AWS SageMaker, Google Colab) pre‑install torchvision in their deep learning environments. Independent wrappers like torchvision_experimental extend functionality with custom models and augmentations.
Contribution guidelines
Contributors are welcome to submit bug reports, feature requests, and pull requests via the pytorch/vision GitHub repository. The project follows a standard contribution workflow: fork the repo, create a feature branch, write tests, and submit a PR. Code style follows PEP 8, and new models or datasets should include reference results and evaluation scripts. The maintainers review contributions for correctness, compatibility, and performance.