autotimm 0.7.29

Automated deep learning for computer vision — train image classification, object detection, and segmentation models with 1000+ backbones in minimal code

Train state-of-the-art vision models with minimal code
From prototype to production in minutes, not hours

Documentation • Quick Start • Examples • API Reference

---

v0.7 Changelog

v0.7.28 — Drop Python 3.14 Support

• Removed Python 3.14 from supported versions (now 3.10–3.13)
• Updated CI matrix and documentation to reflect supported range

v0.7.26 — Trainer Test CLI Fix

• Fixed Trainer test CLI command not working correctly

v0.7.25 — Checkpoint Filename Fix

• Fixed ModelCheckpoint creating nested subdirectories when metric names contain / (e.g. val/loss)
• Checkpoint filenames now use _ instead of / (e.g. best-epoch=7-val_loss=0.1234.ckpt)
• Added auto_insert_metric_name=False to prevent Lightning from prepending metric name as a directory

v0.7.24 — Default Monitor Metric Fix

• Fixed bug introduced when val/loss was added as the default monitor metric for checkpointing

v0.7.22 — Bug Fixes

• Miscellaneous bug fixes and stability improvements

v0.7.21 — JIT Export CLI

• New export_jit CLI module (python -m autotimm.export_jit) for exporting trained checkpoints to TorchScript (JIT) format
• Accepts --checkpoint, --output, --task-class, and --input-size arguments
• Automatically detects input size from model hparams when available
• Uses torch.jit.trace for broad compatibility across all task types
• Enables NightFlow's Netron integration to visualize model architectures from completed runs

v0.7.20 — Interpretation CLI

• New interpret_cli CLI module (python -m autotimm.interpret_cli) for running model interpretation from the command line
• Supports all 6 interpretation methods: GradCAM, GradCAM++, IntegratedGradients, SmoothGrad, AttentionRollout, AttentionFlow
• Outputs JSON with heatmap file paths, predicted class, and per-method errors
• Automatically skips attention methods on non-ViT models with descriptive messages
• Enables NightFlow's Interpretation view to run explanations against trained checkpoints

v0.7.19 — Test Metrics Logging & SEO

• Test metrics now logged to CSV logger and JSONL alongside train/val metrics
• SEO meta tags automatically generated for documentation pages

v0.7.18 — Sanity Run Tagging

• Sanity-check validation runs are now tagged so they can be distinguished from real validation runs in logs and frontends

v0.7.17 — Backbone Path Fix

• Fixed model path resolution in backbone.py for edge cases

v0.7.16 — Additional Hyperparameters

• hparams.yaml saved automatically with all hyperparameters for each run
• Enables downstream dashboards to display training configuration alongside metrics

v0.7.15 — Auto-Tuner GPU Guard

• Batch-size finder now auto-disabled on CPU/MPS where VRAM probing is not meaningful
• Prevents unnecessary overhead and failures on non-GPU devices

v0.7.14 — macOS Stability Fixes

• Fixed multiprocessing issues on macOS (fork vs. spawn)
• Resolved num_workers bug on Apple Silicon

v0.7.13 — macOS Num Workers Fix

• Automatic safe num_workers selection on macOS to prevent deadlocks

v0.7.12 — macOS Training Bug Fix

• Fixed a training crash on macOS when using MPS accelerator

v0.7.11 — MPS / Apple Silicon Fixes

• Resolved torch.compile incompatibilities on Apple MPS backend
• Graceful fallback when deterministic algorithms are unavailable on MPS

v0.7.10 — Loguru Logging & Dependency Cleanup

Logging Migration: rich → loguru

• New autotimm.logging module with a centralized loguru-based logger and log_table() helper
• logger exported at the top level: from autotimm import logger
• All internal print() and rich console output replaced with structured loguru calls (logger.info, logger.warning, logger.success, logger.error) across trainer, export, data modules, interpretation, and YOLOX utilities
• Colored, timestamped log format: HH:mm:ss | LEVEL | module:function - message

Dependency Changes

• loguru>=0.7 added as a core dependency
• plotly>=5.0 promoted from optional [interactive] extra to core dependency
• rich>=13.0 removed as a dependency
• [interactive] install extra removed (plotly is now always available)

Removed

• summary() and _print_summary() methods removed from all DataModules (ImageDataModule, DetectionDataModule, SegmentationDataModule, InstanceSegmentationDataModule, MultiLabelImageDataModule)
• AutoTrainer._print_summaries() removed — pre-training model/data summary printing is no longer automatic

v0.7.9 — Reproducibility by Default

• Default random seeding (seed=42, deterministic=True) for all task classes and AutoTrainer
• New seed_everything() utility function
• Trainer supports use_autotimm_seeding flag to choose between Lightning's seeding and AutoTimm's custom seeding

v0.7.8 — torch.compile Integration

• torch.compile() enabled by default for all task types (compile_model=True)
• Compiles backbone, heads, FPN, neck across all architectures
• Graceful fallback on PyTorch < 2.0

v0.7.5 — ONNX Export

• ONNX export via export_to_onnx(), load_onnx(), validate_onnx_export(), export_checkpoint_to_onnx()
• model.to_onnx() convenience method on all task models
• Dynamic batch dimension by default

v0.7.2 — TorchScript Export & Model Interpretation

• TorchScript export with export_to_torchscript() and model.to_torchscript()
• 6 interpretation methods (GradCAM, GradCAM++, Integrated Gradients, SmoothGrad, AttentionRollout, AttentionFlow)
• 6 explanation quality metrics
• Interactive Plotly visualizations
• YOLOX official model support
• Smart backend selection and TransformConfig
• CLI support (autotimm fit --config config.yaml)

---

What is AutoTimm?

AutoTimm is a production-ready computer vision framework that combines timm (1000+ pretrained models) with PyTorch Lightning. Train image classifiers, object detectors, and segmentation models with any timm backbone using a simple, intuitive API.

Perfect for:

• Researchers needing reproducible experiments and quick iterations
• Engineers building production ML systems with minimal boilerplate
• Students learning computer vision with modern best practices
• Startups rapidly prototyping vision applications

Why AutoTimm?

Fast From idea to trained model in minutes. Auto-tuning, mixed precision, and multi-GPU out of the box.

Flexible 1000+ backbones, 4 vision tasks, multiple transform backends. Use what works best.

Production Ready 487 tests, comprehensive logging, checkpoint management. Deploy with confidence.

Quick Start

Installation

pip install autotimm

Everything included: PyTorch, timm, PyTorch Lightning, torchmetrics, albumentations, pycocotools, and more.

Optional extras

# Logging backends
pip install autotimm[tensorboard]  # TensorBoard
pip install autotimm[wandb]        # Weights & Biases
pip install autotimm[mlflow]       # MLflow

# All extras
pip install autotimm[all]          # Everything

Your First Model in 30 Seconds

from autotimm import AutoTrainer, ImageClassifier, ImageDataModule, MetricConfig

# Data
data = ImageDataModule(
    data_dir="./data",
    dataset_name="CIFAR10",
    image_size=224,
    batch_size=64,
)

# Metrics
metrics = [
    MetricConfig(
        name="accuracy",
        backend="torchmetrics",
        metric_class="Accuracy",
        params={"task": "multiclass"},
        stages=["train", "val", "test"],
        prog_bar=True,
    )
]

# Model
model = ImageClassifier(
    backbone="resnet18",  # Try efficientnet_b0, vit_base_patch16_224, etc.
    num_classes=10,
    metrics=metrics,
    lr=1e-3,
)

# Train with auto-tuning (finds optimal LR and batch size automatically!)
trainer = AutoTrainer(max_epochs=10)
trainer.fit(model, datamodule=data)

Auto-tuning is enabled by default. Disable with tuner_config=False for manual control.

Key Features

4 Vision Tasks	Classification (single & multi-label) • Object Detection • Semantic Segmentation • Instance Segmentation
1000+ Backbones	ResNet • EfficientNet • ViT • ConvNeXt • Swin • DeiT • BEiT • and more from timm
Model Interpretation	6 explanation methods • 6 quality metrics • Interactive visualizations • Up to 100x speedup
HuggingFace Integration	Load models from HF Hub with hf-hub: prefix + Direct Transformers support
YOLOX Support	Official YOLOX models (nano → X) + YOLOX-style heads with any timm backbone
Advanced Architectures	DeepLabV3+ • FCOS • YOLOX • Mask R-CNN • Feature Pyramids
Auto-Tuning	Automatic LR and batch size finding—enabled by default
Smart Transforms	AI-powered backend recommendations + unified TransformConfig with presets
Multi-Logger Support	TensorBoard • MLflow • Weights & Biases • CSV—use simultaneously
torch.compile Support	Automatic PyTorch 2.0+ optimization • Enabled by default • Configurable modes
CLI Support	YAML-config-driven training from the command line — autotimm fit --config config.yaml
CSV Data Loading	Load any task from CSV files — classification, detection, segmentation, instance segmentation
JSON Progress Events	NDJSON progress callback for frontend integration • Train/val/test lifecycle events • File-based replay
Model Export	TorchScript (.pt) and ONNX (.onnx) export • ONNX Runtime, TensorRT, OpenVINO, CoreML
Production Ready	Mixed precision • Multi-GPU • Gradient accumulation • macOS/MPS native support • 487 tests

Task Examples

Image Classification

from autotimm import ImageClassifier

# Use any timm backbone or HuggingFace model
model = ImageClassifier(
    backbone="efficientnet_b0",  # or "hf-hub:timm/resnet50.a1_in1k"
    num_classes=10,
    metrics=metrics,  # Optional for inference!
)

trainer = AutoTrainer(max_epochs=10)
trainer.fit(model, datamodule=data)

Multi-Label Classification

from autotimm import ImageClassifier, MultiLabelImageDataModule, MetricConfig

# CSV data with columns: image_path, cat, dog, outdoor, indoor
data = MultiLabelImageDataModule(
    train_csv="train.csv",
    image_dir="./images",
    val_csv="val.csv",
    image_size=224,
    batch_size=32,
)
data.setup("fit")

model = ImageClassifier(
    backbone="resnet50",
    num_classes=data.num_labels,
    multi_label=True,       # BCEWithLogitsLoss + sigmoid
    threshold=0.5,
    metrics=[
        MetricConfig(
            name="accuracy",
            backend="torchmetrics",
            metric_class="MultilabelAccuracy",
            params={"num_labels": data.num_labels},
            stages=["train", "val"],
            prog_bar=True,
        ),
    ],
)

trainer = AutoTrainer(max_epochs=10)
trainer.fit(model, datamodule=data)

Object Detection with YOLOX

Official YOLOX (matches paper benchmarks):

from autotimm import YOLOXDetector, DetectionDataModule

model = YOLOXDetector(
    model_name="yolox-s",  # nano, tiny, s, m, l, x
    num_classes=80,
    lr=0.01,
    optimizer="sgd",
    scheduler="yolox",
    total_epochs=300,
)

trainer = AutoTrainer(max_epochs=300, precision="16-mixed")
trainer.fit(model, datamodule=DetectionDataModule(data_dir="./coco", image_size=640))

YOLOX-style head with any timm backbone:

from autotimm import ObjectDetector

model = ObjectDetector(
    backbone="resnet50",  # Experiment with any backbone!
    num_classes=80,
    detection_arch="yolox",
    fpn_channels=256,
)

Complete YOLOX Guide • Quick Reference

Semantic Segmentation

from autotimm import SemanticSegmentor, SegmentationDataModule

model = SemanticSegmentor(
    backbone="resnet50",
    num_classes=19,
    head_type="deeplabv3plus",
    loss_type="combined",  # CE + Dice for better boundaries
)

data = SegmentationDataModule(
    data_dir="./cityscapes",
    format="cityscapes",  # or "coco", "voc", "png"
    image_size=512,
)

trainer = AutoTrainer(max_epochs=100)
trainer.fit(model, datamodule=data)

Instance Segmentation

from autotimm import InstanceSegmentor, InstanceSegmentationDataModule

model = InstanceSegmentor(
    backbone="resnet50",
    num_classes=80,
    mask_loss_weight=1.0,
)

trainer = AutoTrainer(max_epochs=100)
trainer.fit(model, datamodule=InstanceSegmentationDataModule(data_dir="./coco"))

CSV Data Loading

Load data from CSV files instead of folder structures or COCO JSON:

from autotimm import ImageClassifier, ImageDataModule, AutoTrainer

# Classification from CSV (columns: image_path, label)
data = ImageDataModule(
    train_csv="train.csv",
    val_csv="val.csv",
    image_dir="./images",
    image_size=224,
    batch_size=32,
)

model = ImageClassifier(backbone="resnet50", num_classes=10)
trainer = AutoTrainer(max_epochs=10)
trainer.fit(model, datamodule=data)

from autotimm import ObjectDetector, DetectionDataModule

# Detection from CSV (columns: image_path, x_min, y_min, x_max, y_max, label)
data = DetectionDataModule(
    train_csv="annotations.csv",
    image_dir="./images",
    image_size=640,
    batch_size=8,
)

CSV loading is supported for all tasks: classification, object detection, semantic segmentation, and instance segmentation.

CSV Data Loading Guide

Model Interpretation & Explainability

Understand what your models learn and how they make decisions with comprehensive interpretation tools.

Quick Explanation

from autotimm.interpretation import quick_explain

# One-line explanation
result = quick_explain(
    model,
    image,
    method="gradcam",
    save_path="explanation.png"
)

6 Interpretation Methods

from autotimm.interpretation import (
    GradCAM,                # Fast, class-discriminative (CNNs)
    GradCAMPlusPlus,        # Better for multiple objects
    IntegratedGradients,    # Theoretically sound, pixel-level
    SmoothGrad,             # Noise-reduced gradients
    AttentionRollout,       # Vision Transformers
    AttentionFlow,          # Vision Transformers
)

# Use any method
explainer = GradCAM(model)
heatmap = explainer.explain(image, target_class=5)
explainer.visualize(image, heatmap, save_path="gradcam.png")

Quantitative Evaluation

from autotimm.interpretation import ExplanationMetrics

metrics = ExplanationMetrics(model, explainer)

# Faithfulness metrics
deletion = metrics.deletion(image, target_class=5, steps=50)
insertion = metrics.insertion(image, target_class=5, steps=50)

# Stability metric
sensitivity = metrics.sensitivity_n(image, n_samples=50)

# Sanity checks
param_test = metrics.model_parameter_randomization_test(image)
data_test = metrics.data_randomization_test(image)

# Localization metric
pointing = metrics.pointing_game(image, bbox=(50, 50, 150, 150))

print(f"Deletion AUC: {deletion['auc']:.4f}")  # Lower = better
print(f"Insertion AUC: {insertion['auc']:.4f}")  # Higher = better
print(f"Sensitivity: {sensitivity['sensitivity']:.4f}")  # Lower = more stable

Interactive Visualizations

from autotimm.interpretation import InteractiveVisualizer

viz = InteractiveVisualizer(model)

# Create interactive HTML with zoom/pan/hover
fig = viz.visualize_explanation(
    image,
    explainer,
    colorscale="Viridis",
    save_path="interactive.html"
)

# Compare methods side-by-side
explainers = {
    'GradCAM': GradCAM(model),
    'GradCAM++': GradCAMPlusPlus(model),
    'Integrated Gradients': IntegratedGradients(model),
}
viz.compare_methods(image, explainers, save_path="comparison.html")

# Generate comprehensive report
viz.create_report(image, explainer, save_path="report.html")

Performance Optimization

from autotimm.interpretation.optimization import (
    ExplanationCache,        # 10-50x speedup
    BatchProcessor,          # 2-5x speedup
    PerformanceProfiler,     # Identify bottlenecks
    optimize_for_inference,  # 1.5-3x speedup
)

# Enable caching
cache = ExplanationCache(cache_dir="./cache", max_size_mb=5000)

# Optimize model
model = optimize_for_inference(model, use_fp16=True)

# Batch processing
processor = BatchProcessor(model, explainer, batch_size=32)
heatmaps = processor.process_batch(images)

# Profile performance
profiler = PerformanceProfiler(enabled=True)
with profiler.profile("explanation"):
    heatmap = explainer.explain(image)
profiler.print_stats()

Training Integration

from autotimm import AutoTrainer
from autotimm.interpretation import InterpretationCallback

# Monitor interpretations during training
callback = InterpretationCallback(
    sample_images=val_images,
    method="gradcam",
    log_every_n_epochs=5,
)

trainer = AutoTrainer(
    max_epochs=100,
    callbacks=[callback],
    logger="tensorboard",
)
trainer.fit(model, datamodule=data)

Features:

• 6 interpretation methods for different use cases
• 6 quality metrics for quantitative evaluation
• Interactive visualizations with Plotly (zoom/pan/hover)
• Up to 100x speedup with caching and optimization
• Feature visualization and receptive field analysis
• Training callbacks for automatic monitoring
• Comprehensive tutorial notebook included

Interpretation Guide • Tutorial Notebook

HuggingFace Integration

Three Approaches

Approach	Best For	Example
HF Hub timm	CNNs, Production	"hf-hub:timm/resnet50.a1_in1k"
HF Transformers Direct	Vision Transformers	ViTModel.from_pretrained(...)
HF Transformers Auto	Quick Prototyping	AutoModel.from_pretrained(...)

All approaches fully support AutoTrainer (checkpointing, early stopping, mixed precision, multi-GPU, auto-tuning).

from autotimm import ImageClassifier, list_hf_hub_backbones

# Discover models
models = list_hf_hub_backbones(model_name="resnet", limit=5)

# Use any HF Hub model (just add 'hf-hub:' prefix!)
model = ImageClassifier(
    backbone="hf-hub:timm/convnext_base.fb_in22k_ft_in1k",
    num_classes=100,
)

HF Integration Comparison • HF Hub Guide • HF Transformers Guide

Smart Features

torch.compile Optimization

Enabled by default for all tasks with PyTorch 2.0+:

# Default: torch.compile enabled for faster training/inference
model = ImageClassifier(backbone="resnet50", num_classes=10)

# Disable if needed
model = ImageClassifier(backbone="resnet50", num_classes=10, compile_model=False)

# Custom compile options
model = ImageClassifier(
    backbone="resnet50",
    num_classes=10,
    compile_kwargs={"mode": "reduce-overhead", "fullgraph": True}
)

Compile modes:

• "default" - Balanced performance (default)
• "reduce-overhead" - Lower latency, better for smaller batches
• "max-autotune" - Maximum optimization, longer compile time

What gets compiled:

• Classification: backbone + head
• Detection: backbone + FPN/neck + head
• Segmentation: backbone + segmentation head
• Instance Segmentation: backbone + FPN + detection head + mask head

Gracefully falls back on PyTorch < 2.0 with a warning.

Reproducibility by Default

Automatic seeding for reproducible experiments:

# Default: seed=42, deterministic=True for full reproducibility
model = ImageClassifier(backbone="resnet50", num_classes=10)
trainer = AutoTrainer(max_epochs=10)

# Custom seed
model = ImageClassifier(backbone="resnet50", num_classes=10, seed=123)
trainer = AutoTrainer(max_epochs=10, seed=123)

# Faster training (disable deterministic mode)
model = ImageClassifier(backbone="resnet50", num_classes=10, deterministic=False)
trainer = AutoTrainer(max_epochs=10, deterministic=False)

# Disable seeding (warns if deterministic=True)
model = ImageClassifier(backbone="resnet50", num_classes=10, seed=None, deterministic=False)

# Manual seeding
from autotimm import seed_everything
seed_everything(42, deterministic=True)

What's seeded:

• Python's random module
• NumPy's random number generator
• PyTorch (CPU & CUDA)
• Environment variables for reproducibility
• cuDNN deterministic algorithms (when deterministic=True)

Seeding options:

• Model-level: Seeds when model is created
• Trainer-level: Seeds before training starts (uses Lightning's seeding by default)
• Manual: Use seed_everything() for custom control

Perfect for research papers, debugging, and ensuring consistent results across runs!

Model Export (TorchScript & ONNX)

Export trained models for production deployment:

from autotimm import ImageClassifier, export_to_torchscript, export_to_onnx
import torch

model = ImageClassifier.load_from_checkpoint("model.ckpt")
example_input = torch.randn(1, 3, 224, 224)

# TorchScript export
export_to_torchscript(model, "model.pt", example_input=example_input)
model.to_torchscript("model.pt")  # Convenience method

# ONNX export
export_to_onnx(model, "model.onnx", example_input=example_input)
model.to_onnx("model.onnx")  # Convenience method

# Load TorchScript (no AutoTimm needed)
scripted_model = torch.jit.load("model.pt")
output = scripted_model(image)

# Load ONNX (no AutoTimm needed)
import onnxruntime as ort
session = ort.InferenceSession("model.onnx")
outputs = session.run(None, {"input": image.numpy()})

Format	Use Case	Runtimes
TorchScript	PyTorch ecosystem, C++, mobile	LibTorch, PyTorch Mobile
ONNX	Cross-platform, hardware-optimized	ONNX Runtime, TensorRT, OpenVINO, CoreML

Shared benefits: No Python dependencies, single-file deployment, dynamic batch sizes, all 5 task types supported.

Smart Backend Selection

from autotimm import recommend_backend, compare_backends

# Get AI-powered recommendation
rec = recommend_backend(task="detection")
config = rec.to_config(image_size=640)

# Compare backends side-by-side
compare_backends()

Unified Transform Configuration

from autotimm import TransformConfig, list_transform_presets

# Discover presets
list_transform_presets()  # ['default', 'autoaugment', 'randaugment', ...]

# Configure with model-specific normalization
config = TransformConfig(
    preset="randaugment",
    image_size=384,
    use_timm_config=True,  # Auto-detect mean/std from backbone
)

model = ImageClassifier(
    backbone="efficientnet_b4",
    num_classes=10,
    transform_config=config,
)

Custom Auto-Tuning

from autotimm import AutoTrainer, TunerConfig

# Default: Full auto-tuning
trainer = AutoTrainer(max_epochs=10)

# Disable auto-tuning
trainer = AutoTrainer(max_epochs=10, tuner_config=False)

# Custom configuration
trainer = AutoTrainer(
    max_epochs=10,
    tuner_config=TunerConfig(
        auto_lr=True,
        auto_batch_size=True,
        lr_find_kwargs={"min_lr": 1e-6, "max_lr": 1.0},
    ),
)

Command-Line Interface (CLI)

Train models from the command line using YAML configs — no Python scripts needed:

# Train with a config file
autotimm fit --config config.yaml

# Override any parameter
autotimm fit --config config.yaml --model.init_args.lr 0.001 --trainer.max_epochs 20

# Quick smoke test
autotimm fit --config config.yaml --trainer.fast_dev_run true

# Validate or test
autotimm validate --config config.yaml --ckpt_path best.ckpt
autotimm test --config config.yaml --ckpt_path best.ckpt

Example config.yaml:

model:
  class_path: autotimm.ImageClassifier
  init_args:
    backbone: resnet18
    num_classes: 10

data:
  class_path: autotimm.ImageDataModule
  init_args:
    dataset_name: CIFAR10
    data_dir: ./data
    batch_size: 32
    image_size: 224

trainer:
  max_epochs: 10
  accelerator: auto
  tuner_config: false

Works with all task types: classification, detection, segmentation, and instance segmentation. See example configs for more.

CLI Guide | CLI API Reference

Optional Metrics for Inference

# Training with metrics
model = ImageClassifier(backbone="resnet50", num_classes=10, metrics=metrics)

# Inference without metrics
model = ImageClassifier(backbone="resnet50", num_classes=10)
model = model.load_from_checkpoint("checkpoint.ckpt")
predictions = model(image)

Explore Models

YOLOX Models

import autotimm

# List all YOLOX variants
autotimm.list_yolox_models()  # ['yolox-nano', 'yolox-tiny', 'yolox-s', ...]

# Get detailed specs (params, FLOPs, mAP)
autotimm.list_yolox_models(verbose=True)

# Get model info
info = autotimm.get_yolox_model_info("yolox-s")
print(f"Params: {info['params']}, mAP: {info['mAP']}")  # Params: 9.0M, mAP: 40.5

# List components
autotimm.list_yolox_backbones()
autotimm.list_yolox_necks()
autotimm.list_yolox_heads()

timm Backbones

# Search 1000+ timm models
autotimm.list_backbones("*efficientnet*", pretrained_only=True)
autotimm.list_backbones("*vit*")

# Search HuggingFace Hub
autotimm.list_hf_hub_backbones(model_name="resnet", limit=10)

# Inspect a model
backbone = autotimm.create_backbone("convnext_tiny")
print(f"Features: {backbone.num_features}, Params: {autotimm.count_parameters(backbone):,}")

Documentation & Examples

Documentation

Comprehensive documentation with interactive diagrams, search optimization, and fast navigation:

Section	Description
Quick Start	Get up and running in 5 minutes
User Guide	In-depth guides for all features
Interpretation Guide	Model explainability and visualization
YOLOX Guide	Complete YOLOX implementation guide
CLI Guide	Train from YAML configs on the command line
API Reference	Complete API documentation
Examples	50+ runnable code examples

Ready-to-Run Examples

🚀 Getting Started

• classify_cifar10.py - Basic classification with auto-tuning
• classify_custom_folder.py - Train on custom dataset
• vit_finetuning.py - Two-phase ViT fine-tuning

🎯 Computer Vision Tasks

• Object Detection: yolox_official.py, object_detection_yolox.py, object_detection_coco.py, object_detection_rtdetr.py
• Segmentation: semantic_segmentation.py, instance_segmentation.py

🤗 HuggingFace Hub (14 examples)

• Basic: huggingface_hub_models.py, hf_hub_*.py (8 task-specific files)
• Advanced: hf_interpretation.py, hf_transfer_learning.py, hf_ensemble.py, hf_deployment.py

📊 Data & Training

• CSV Data: csv_classification.py, csv_detection.py, csv_segmentation.py, csv_instance_segmentation.py
• Data: multilabel_classification.py - Multi-label from CSV, hf_custom_data.py - Advanced augmentation
• Training: multi_gpu_training.py, hf_hyperparameter_tuning.py
• Optimization: preset_manager.py, performance_optimization_demo.py

🔍 Model Understanding

• Interpretation: comprehensive_interpretation_tutorial.ipynb (40+ cells), interpretation_metrics_demo.py
• Visualization: interactive_visualization_demo.py - Interactive Plotly
• Tracking: mlflow_tracking.py - MLflow experiment tracking

:material-console: CLI Configs

• classification.yaml - Classification with ResNet-18 on CIFAR-10
• detection.yaml - FCOS object detection on COCO
• segmentation.yaml - DeepLabV3+ on Cityscapes

Browse all examples →

Supported Architectures

Classification

• Models: Any timm backbone (1000+)
• Losses: CrossEntropy with label smoothing, Mixup; BCEWithLogitsLoss for multi-label

Object Detection

• Architectures: FCOS, YOLOX (official & custom)
• Losses: Focal Loss, GIoU Loss, Centerness Loss

Semantic Segmentation

• Architectures: DeepLabV3+, FCN
• Losses: CrossEntropy, Dice, Focal, Combined, Tversky
• Formats: PNG masks, COCO stuff, Cityscapes, Pascal VOC, CSV

Instance Segmentation

• Architecture: FCOS + Mask R-CNN style mask head
• Losses: Detection losses + Binary mask loss
• Formats: COCO JSON, CSV with binary mask PNGs

Testing

Comprehensive test suite with 487 tests:

# Run all tests
pytest tests/ -v

# Specific modules
pytest tests/test_classification.py
pytest tests/test_yolox.py
pytest tests/test_interpretation.py
pytest tests/test_csv_datamodules.py

# With coverage
pytest tests/ --cov=autotimm --cov-report=html

Contributing

We welcome contributions!

git clone https://github.com/theja-vanka/AutoTimm.git
cd AutoTimm
pip install -e ".[dev,all]"
pytest tests/ -v

To build the documentation locally:

./scripts/build_docs.sh

For more details, see scripts/README.md.

For major changes, please open an issue first.

Citation

@software{autotimm,
  author = {Krishnatheja Vanka},
  title = {AutoTimm: Automatic PyTorch Image Models},
  url = {https://github.com/theja-vanka/AutoTimm},
  year = {2026},
  version = {0.7.29}
}

---

Built with ❤️ using timm and PyTorch Lightning

Star us on GitHub • Report Issues • Read the Docs