PyTorch 图像模型

• 新增内容
• 简介
• 模型
• 特性
• 结果
• 入门指南（文档）
• 训练、验证、推理脚本
• 优秀的 PyTorch 资源
• 许可证
• 引用

新增内容

2026年3月23日

• 改进 pickle 检查点处理的安全性。默认所有加载操作都设置为 weights_only=True，并为 ArgParse 添加安全全局变量。
• 改进核心 ViT/EVA 模型及层的注意力掩码处理。解析布尔掩码，并将 is_causal 参数传递给 SSL 任务。
• 修复在启用 ViT 且未使用位置嵌入时的类和注册标记用法问题。
• 在 ViT 中添加补丁表示精炼 (PRR) 作为池化选项。感谢 Sina (https://github.com/sinahmr)。
• 提高注意力池化层输出投影/MLP 维度的一致性。
• 对 Hiera 模型进行 F.SDPA 优化，以支持 Flash Attention 内核的使用。
• 向 SGDP 优化器添加警告信息。
• 发布 1.0.26 版本。这是我离开 Hugging Face 以来的首个维护版本。

2026年2月23日

• 在蒸馏任务包装器中添加标记蒸馏训练支持。
• 为正式弃用做准备，移除部分 torch.jit 的使用。
• 向 AdamP 优化器添加警告信息。
• 即使是元设备初始化，也调用 reset_parameters() 方法，以便使用诸如 init_empty_weights 等技巧来初始化缓冲区。
• 调整 Muon 优化器，使其与 DTensor/FSDP2 兼容（使用 clamp_ 而不是 clamp_min_，为 DTensor 使用替代的 NS 分支）。
• 发布 1.0.25 版本。

2026年1月21日

• 兼容性破坏：修复 ParallelScalingBlock（以及 DiffParallelScalingBlock）中 QKV 和 MLP 偏置的疏忽。
  • 这不会影响任何已训练的 timm 模型，但可能会影响下游应用。

2026年1月5日和6日

• 发布 1.0.24 版本。
• 添加新的基准测试结果 CSV 文件，用于在 RTX Pro 6000、5090 和 4090 显卡上，使用 PyTorch 2.9.1 进行所有模型的推理时间测试。
• 修复已弃用的 timm.models.layers 导入路径中的模块移动错误，该错误影响旧版导入。
• 发布 1.0.23 版本。

2025年12月30日

• 添加性能更好的 NAdaMuon 训练的 dpwee、dwee、dlittle（差异）ViT 模型，相比之前的运行略有提升。
  • https://huggingface.co/timm/vit_dlittle_patch16_reg1_gap_256.sbb_nadamuon_in1k（83.24% top-1）
  • https://huggingface.co/timm/vit_dwee_patch16_reg1_gap_256.sbb_nadamuon_in1k（81.80% top-1）
  • https://huggingface.co/timm/vit_dpwee_patch16_reg1_gap_256.sbb_nadamuon_in1k（81.67% top-1）
• 在 512x512 和 640x640 尺寸下，添加一个约 2100 万参数的 timm 变体 CSATv2 模型。
  • https://huggingface.co/timm/csatv2_21m.sw_r640_in1k（83.13% top-1）
  • https://huggingface.co/timm/csatv2_21m.sw_r512_in1k（82.58% top-1）
• 将非持久化参数的初始化从 __init__ 方法中提取出来，放入一个公共方法中，可在元设备初始化后通过 init_non_persistent_buffers() 外部调用。

2025年12月12日

• 添加 CSATV2 模型（感谢 https://github.com/gusdlf93）——一种轻量级但高分辨率的模型，带有 DCT 主干和空间注意力。https://huggingface.co/Hyunil/CSATv2。
• 在现有的 timm Muon 实现中添加 AdaMuon 和 NAdaMuon 优化器支持。对于图像任务，它似乎比 AdamW 更具竞争力，且具有熟悉的超参数。
• 年终 PR 清理，合并多个长期开放的 PR。
  • 合并差异注意力 (DiffAttention)，添加相应的 DiffParallelScalingBlock（适用于 ViT），并训练一些小型 ViT 模型。
    • https://huggingface.co/timm/vit_dwee_patch16_reg1_gap_256.sbb_in1k。
    • https://huggingface.co/timm/vit_dpwee_patch16_reg1_gap_256.sbb_in1k。
  • 添加几个池化模块，如 LsePlus 和 SimPool。
  • 清理并优化 DropBlock2d（同时为 ByobNet 基础模型添加支持）。
• 将单元测试升级到 PyTorch 2.9.1 和 Python 3.13 的较高版本，而较低版本仍保持 PyTorch 1.13 和 Python 3.10。

2025年12月1日

• 添加轻量级任务抽象，通过新任务在训练脚本中支持 logits 和特征蒸馏。
• 移除旧的 APEX AMP 支持。

2025年11月4日

• 修复 LayerScale / LayerScale2d 初始化错误（初始值被忽略），该错误是在 1.0.21 版本中引入的。感谢 https://github.com/Ilya-Fradlin。
• 发布 1.0.22 版本。

2025年10月31日 🎃

• 更新 ImageNet 和 OOD 变体结果 CSV 文件，加入几款新模型，并在多个 PyTorch 和 timm 版本中验证其正确性。
• 添加 EfficientNet-X 和 EfficientNet-H B5 模型权重，作为 AdamW 与 Muon 超参数搜索的一部分（仍在迭代 Muon 运行）。

2025年10月16日至20日

• 添加基于 https://github.com/KellerJordan/Muon 的 Muon 优化器实现，并进行定制。
  • 提供额外的灵活性，改进对卷积权重的处理，并为不适合正交化的权重形状提供回退机制。
  • 通过减少内存分配和使用融合的 (b)add(b)mm 操作，小幅提升了 NS 迭代的速度。
  • 默认情况下，如果参数形状不适合使用 Muon（或通过参数组标志排除），则会使用 AdamW（或若 nesterov=True 则使用 NAdamW）更新。
  • 类似于 PyTorch 实现，可通过 adjust_lr_fn 选择多种 LR 缩放调整函数。
  • 可以选择几种 NS 系数预设，或通过 ns_coefficients 自定义自己的系数。
• 支持“meta”设备模型初始化的前两步。
  • 修复了几种在“meta”设备上下文中创建时会出错的操作。
  • 在 timm 中的所有模型和模块（任何继承自 nn.Module 的对象）中添加了设备和 dtype 工厂关键字参数的支持。
• 在代码中的预训练配置文件中添加了许可证字段。
• 发布 1.0.21 版本。

2025年9月21日

• 将 DINOv3 ViT 权重标签从 lvd_1689m 重新映射为 lvd1689m，以保持一致（同样适用于 sat_493m -> sat493m）。
• 发布 1.0.20 版本。

2025年9月17日

• 添加 DINOv3（https://arxiv.org/abs/2508.10104）ConvNeXt 和 ViT 模型。ConvNeXt 模型被映射到现有的 timm 模型。ViT 支持则通过 EVA 基础模型实现，并使用新的 RotaryEmbeddingDinoV3 来匹配 DINOv3 特有的 RoPE 实现。
  • HuggingFace Hub: https://huggingface.co/collections/timm/timm-dinov3-68cb08bb0bee365973d52a4d。
• MobileCLIP-2（https://arxiv.org/abs/2508.20691）视觉编码器。添加了新的 MCI3/MCI4 FastViT 变体，并将权重映射到现有的 FastViT 和 B、L/14 ViT 模型。
• 添加 MetaCLIP-2 Worldwide（https://arxiv.org/abs/2507.22062）ViT 编码器权重。
• 通过 timm NaFlexViT 模型添加 SigLIP-2（https://arxiv.org/abs/2502.14786）NaFlex ViT 编码器权重。
• 其他修复和贡献。

2025年7月23日

• 在 EVA 模型中添加 set_input_size() 方法，OpenCLIP 3.0.0 使用该方法允许对基于 timm 的编码器模型进行大小调整。
• 发布 1.0.18 版本，这是 OpenCLIP 3.0.0 中 PE-Core S 和 T 模型所需的版本。
• 修复一个小的类型问题，该问题导致 Python 3.9 不兼容。发布 1.0.19 补丁版本。

2025年7月21日

• NaFlexViT新增ROPE支持。所有由EVA基础模块（eva.py）覆盖的模型，包括EVA、EVA02、Meta PE ViT、带有ROPE的timm SBB ViT以及Naver ROPE-ViT，现在都可以在创建模型时传入use_naflex=True参数后加载到NaFlexViT中。
• 增加了更多Meta PE ViT编码器，包括小型/微型变体、带分块处理的语言变体，以及更多空间变体。
• 修复了NaFlexViT及EVA模型中的PatchDropout问题（在添加Naver ROPE-ViT后出现的回归问题）。
• 修正了grid_indexing='xy'模式下的XY顺序问题，该问题影响了在‘xy’模式下使用非正方形图像的情况（仅ROPE-ViT和PE受影响）。

2025年7月7日

• 对MobileNet-v5主干网络进行了调整，以改善Google Gemma 3n的表现（配合更新的官方权重）：
  • 添加了stem偏置项（在更新的权重中已置零，与旧权重不兼容）；
  • 将激活函数从GELU改为GELU（tanh近似）。这一小幅改动旨在更接近JAX实现。
• 为层衰减支持新增两个参数：最小缩放系数限制和“无优化”缩放阈值。
• 新增‘Fp32’版本的LayerNorm、RMSNorm和SimpleNorm变体，可启用以强制在float32精度下进行归一化计算。
• 针对上述内容，对归一化层及其激活组合层的类型注解和参数进行了清理。
• 在eva.py中支持Naver ROPE-ViT（https://github.com/naver-ai/rope-vit），并新增RotaryEmbeddingMixed模块用于混合模式，权重已发布至HuggingFace Hub。

模型	图像尺寸	Top-1准确率	Top-5准确率	参数量
vit_large_patch16_rope_mixed_ape_224.naver_in1k	224	84.84	97.122	304.4
vit_large_patch16_rope_mixed_224.naver_in1k	224	84.828	97.116	304.2
vit_large_patch16_rope_ape_224.naver_in1k	224	84.65	97.154	304.37
vit_large_patch16_rope_224.naver_in1k	224	84.648	97.122	304.17
vit_base_patch16_rope_mixed_ape_224.naver_in1k	224	83.894	96.754	86.59
vit_base_patch16_rope_mixed_224.naver_in1k	224	83.804	96.712	86.44
vit_base_patch16_rope_ape_224.naver_in1k	224	83.782	96.61	86.59
vit_base_patch16_rope_224.naver_in1k	224	83.718	96.672	86.43
vit_small_patch16_rope_224.naver_in1k	224	81.23	95.022	21.98
vit_small_patch16_rope_mixed_224.naver_in1k	224	81.216	95.022	21.99
vit_small_patch16_rope_ape_224.naver_in1k	224	81.004	95.016	22.06
vit_small_patch16_rope_mixed_ape_224.naver_in1k	224	80.986	94.976	22.06

• 对ROPE模块、辅助工具及FX追踪叶节点注册进行了部分清理。
• 正在准备1.0.17版本发布。

2025年6月26日

• 提供了适用于Gemma 3n图像编码器的MobileNetV5主干网络（仅含编码器变体）。
• 发布了1.0.16版本。

2025年6月23日

• 在NaFlexViT中新增基于F.grid_sample的2D及因子化位置编码插值功能。当需要处理大量不同尺寸时，此方法更为高效（参考自https://github.com/stas-sl的示例）。
• 进一步加速patch嵌入重采样过程，将vmap替换为矩阵乘法（参考自https://github.com/stas-sl的代码片段）。
• 在测试过程中生成了3个初始的原生宽高比NaFlexViT检查点，分别对应ImageNet-1k数据集及3种不同的位置编码配置，且具有相同的超参数。

模型	Top-1准确率	Top-5准确率	参数量（M）	评估序列长度
naflexvit_base_patch16_par_gap.e300_s576_in1k	83.67	96.45	86.63	576
naflexvit_base_patch16_parfac_gap.e300_s576_in1k	83.63	96.41	86.46	576
naflexvit_base_patch16_gap.e300_s576_in1k	83.50	96.46	86.63	576

• 支持forward_intermediates梯度检查点，并修复了一些检查点相关的bug。感谢https://github.com/brianhou0208的贡献。
• 将AdamW（传统）、Adopt、Kron、Adafactor（BV）、Lamb、LaProp、Lion、NadamW、RmsPropTF、SGDW等优化器的权重衰减选项更新为“修正版权重衰减”（https://arxiv.org/abs/2506.02285）。
• 将PE（感知编码器）ViT模型切换为使用原生timm权重，而非实时重新映射。
• 修复了预取加载器中的CUDA流bug。

2025年6月5日

• 初始的NaFlexVit模型代码。NaFlexVit是一种视觉Transformer，具备以下特性：
  1. 将嵌入和位置编码封装在一个模块中；
  2. 支持对预分割（字典形式）输入进行nn.Linear patch嵌入；
  3. 支持NaFlex的可变宽高比和分辨率（SigLip-2：https://arxiv.org/abs/2502.14786）；
  4. 支持FlexiViT的可变patch大小（https://arxiv.org/abs/2212.08013）；
  5. 支持NaViT的分数/因子化位置编码（https://arxiv.org/abs/2307.06304）。
• 现有的vision_transformer.py中的ViT模型可以通过在create_model中添加use_naflex=True标志加载到NaFlexVit模型中。
  • 部分原生权重即将推出。
• 提供了一套完整的NaFlex数据流水线，支持使用可变宽高比/尺寸的图像进行训练/微调/评估。
  • 在train.py和validate.py中添加--naflex-loader参数即可启用，但必须与NaFlexVit模型配合使用。
• 使用NaFlex数据流水线评估已加载到NaFlexVit模型中的现有（经典）ViT模型：
  • python validate.py /imagenet --amp -j 8 --model vit_base_patch16_224 --model-kwargs use_naflex=True --naflex-loader --naflex-max-seq-len 256
• 训练过程中还有一些值得注意的额外参数功能：
  • --naflex-train-seq-lens参数指定了训练时每批次随机选择的序列长度范围；
  • --naflex-max-seq-len参数设置了验证时的目标序列长度；
  • 添加--model-kwargs enable_patch_interpolator=True --naflex-patch-sizes 12 16 24将启用每批次随机选择patch大小并进行插值的功能；
  • --naflex-loss-scale参数会根据批次大小动态调整损失缩放模式，而timm的NaFlex加载方式会为每个序列长度调整批次大小。

2025年5月28日

• 感谢 https://github.com/brianhou0208 的贡献，新增了一批小型/快速模型：
  • SwiftFormer - (ICCV2023) SwiftFormer：用于基于Transformer的实时移动视觉应用的高效加性注意力机制
  • FasterNet - (CVPR2023) 跑起来，别走着：追求更高FLOPS以实现更快的神经网络
  • SHViT - (CVPR2024) SHViT：具有内存效率的单头视觉Transformer
  • StarNet - (CVPR2024) 重写星辰
  • GhostNet-V3 GhostNetV3：探索紧凑模型的训练策略
• 更新EVA ViT（最接近的匹配）以支持Meta的Perception Encoder模型（https://arxiv.org/abs/2504.13181），加载Hub权重，但我仍需推送专门的`timm`权重。
  • 为ROPE实现增加了一些灵活性。
• 在https://github.com/brianhou0208的帮助下，支持`forward_intermediates()`的模型数量大幅增加，并进行了一些额外的修复。
  • 包括DaViT、EdgeNeXt、EfficientFormerV2、EfficientViT(MIT)、EfficientViT(MSRA)、FocalNet、GCViT、HGNet /V2、InceptionNeXt、Inception-V4、MambaOut、MetaFormer、NesT、Next-ViT、PiT、PVT V2、RepGhostNet、RepViT、ResNetV2、ReXNet、TinyViT、TResNet、VoV等。
• TNT模型已使用新权重更新了forward_intermediates()，感谢https://github.com/brianhou0208。
• 添加local-dir:预训练模式，可以使用local-dir:/path/to/model/folder作为模型名称，从本地文件夹中加载Hugging Face Hub模型的配置文件和权重文件。
• 修复并改进了ONNX导出功能。

2025年2月21日

• 新增SigLIP 2 ViT图像编码器（https://huggingface.co/collections/timm/siglip-2-67b8e72ba08b09dd97aecaf9）。
  • 可变分辨率/宽高比的NaFlex版本仍在开发中。
• 新增采用SBB配方训练的‘SO150M2’ViT权重，效果极佳，相比之前的尝试，在ImageNet上的表现更好，且训练量更少。
  • vit_so150m2_patch16_reg1_gap_448.sbb_e200_in12k_ft_in1k - Top-1准确率88.1%
  • vit_so150m2_patch16_reg1_gap_384.sbb_e200_in12k_ft_in1k - Top-1准确率87.9%
  • vit_so150m2_patch16_reg1_gap_256.sbb_e200_in12k_ft_in1k - Top-1准确率87.3%
  • vit_so150m2_patch16_reg4_gap_256.sbb_e200_in12k
• 更新InternViT-300M ‘2.5’权重。
• 发布1.0.15版本。

2025年2月1日

• 特别说明：PyTorch 2.6和Python 3.13已在当前主分支及发布的timm版本中测试通过并正常工作。

2025年1月27日

• 新增Kron优化器（带有克罗内克分解预条件的PSGD）。
  • 代码来自https://github.com/evanatyourservice/kron_torch。
  • 更多信息请参见https://sites.google.com/site/lixilinx/home/psgd。

2025年1月19日

• 修复LeViT safetensor权重的加载问题，移除本应已停用的转换代码。
• 新增采用SBB配方训练的‘SO150M’ViT权重，效果尚可，但其形状并不适合ImageNet-12k/1k的预训练和微调。
  • vit_so150m_patch16_reg4_gap_256.sbb_e250_in12k_ft_in1k - Top-1准确率86.7%
  • vit_so150m_patch16_reg4_gap_384.sbb_e250_in12k_ft_in1k - Top-1准确率87.4%
  • vit_so150m_patch16_reg4_gap_256.sbb_e250_in12k
• 进行了一些类型注解、拼写错误等方面的清理。
• 发布1.0.14版本以修复上述LeViT问题。

2025年1月9日

• 增加对纯bfloat16或float16训练和验证的支持。
• 由https://github.com/caojiaolong添加了`wandb`项目名称参数，使用arg.experiment指定名称。
• 修复旧问题：在不支持硬链接的文件系统上无法保存检查点（例如FUSE挂载的文件系统）。
• 发布1.0.13版本。

2025年1月6日

• 在timm.models中添加torch.utils.checkpoint.checkpoint()包装器，默认设置use_reentrant=False，除非环境变量TIMM_REENTRANT_CKPT=1被设置。

2024年12月31日

• convnext_nano 384x384 ImageNet-12k预训练及微调模型。https://huggingface.co/models?search=convnext_nano%20r384
• 新增来自https://github.com/apple/ml-aim的AIM-v2编码器，可在Hub上查看：https://huggingface.co/models?search=timm%20aimv2
• 将来自https://github.com/google-research/big_vision的PaliGemma2编码器添加到现有的PaliGemma中，可在Hub上查看：https://huggingface.co/models?search=timm%20pali2
• 补齐缺失的L/14 DFN2B 39B CLIP ViT，即vit_large_patch14_clip_224.dfn2b_s39b
• 修复现有的RmsNorm层及函数，使其符合标准公式，尽可能使用PT 2.5的实现。将旧实现移至SimpleNorm层，该层为LN，但不含中心化或偏置。此前仅有两台timm模型使用它，现已完成更新。
• 允许覆盖模型创建时的cache_dir参数。
• 将trust_remote_code传递给HF数据集包装器。
• 创作者新增了inception_next_atto模型。
• 提醒注意Adan优化器以及Lamb解耦合权重衰减选项。
• 由https://github.com/brianhou0208修复了一些feature_info元数据。
• 所有使用加载时重新映射的OpenCLIP和JAX（CLIP、SigLIP、Pali等）模型权重均已分配独立的HF Hub实例，以便通过hf-hub:方式加载，从而与新的Transformers TimmWrapperModel兼容。

简介

PyTorch Image Models (timm) 是一个包含图像模型、层、工具、优化器、调度器、数据加载器/增强以及参考训练/验证脚本的集合，旨在汇集各种最先进的模型，并具备重现ImageNet训练结果的能力。 此处包含了众多他人的工作成果。我已尽力确保所有来源材料均在README、文档和代码注释中通过GitHub、arXiv论文等链接予以注明。如有遗漏，请随时告知我。

功能

模型

所有模型架构系列均包含带有预训练权重的变体。也有一些特定的模型变体未附带任何权重，这并非错误。我们始终欢迎帮助训练新的或更好的权重。

• 聚合嵌套Transformer - https://arxiv.org/abs/2105.12723
• BEiT - https://arxiv.org/abs/2106.08254
• BEiT-V2 - https://arxiv.org/abs/2208.06366
• BEiT3 - https://arxiv.org/abs/2208.10442
• 大迁移ResNetV2 (BiT) - https://arxiv.org/abs/1912.11370
• 瓶颈Transformer - https://arxiv.org/abs/2101.11605
• CaiT（图像Transformer中的类别注意力） - https://arxiv.org/abs/2103.17239
• CoaT（协同尺度卷积-注意力图像Transformer） - https://arxiv.org/abs/2104.06399
• CoAtNet（卷积与注意力） - https://arxiv.org/abs/2106.04803
• ConvNeXt - https://arxiv.org/abs/2201.03545
• ConvNeXt-V2 - http://arxiv.org/abs/2301.00808
• ConViT（具有软卷积归纳偏置的视觉Transformer） - https://arxiv.org/abs/2103.10697
• CspNet（跨阶段部分网络） - https://arxiv.org/abs/1911.11929
• DeiT - https://arxiv.org/abs/2012.12877
• DeiT-III - https://arxiv.org/pdf/2204.07118.pdf
• DenseNet - https://arxiv.org/abs/1608.06993
• DLA - https://arxiv.org/abs/1707.06484
• DPN（双路径网络） - https://arxiv.org/abs/1707.01629
• EdgeNeXt - https://arxiv.org/abs/2206.10589
• EfficientFormer - https://arxiv.org/abs/2206.01191
• EfficientFormer-V2 - https://arxiv.org/abs/2212.08059
• EfficientNet（MBConvNet家族）
  • EfficientNet NoisyStudent（B0-B7，L2） - https://arxiv.org/abs/1911.04252
  • EfficientNet AdvProp（B0-B8） - https://arxiv.org/abs/1911.09665
  • EfficientNet（B0-B7） - https://arxiv.org/abs/1905.11946
  • EfficientNet-EdgeTPU（S、M、L） - https://ai.googleblog.com/2019/08/efficientnet-edgetpu-creating.html
  • EfficientNet V2 - https://arxiv.org/abs/2104.00298
  • FBNet-C - https://arxiv.org/abs/1812.03443
  • MixNet - https://arxiv.org/abs/1907.09595
  • MNASNet B1、A1（挤压-激励）以及Small - https://arxiv.org/abs/1807.11626
  • MobileNet-V2 - https://arxiv.org/abs/1801.04381
  • 单路径NAS - https://arxiv.org/abs/1904.02877
  • TinyNet - https://arxiv.org/abs/2010.14819
• EfficientViT（MIT） - https://arxiv.org/abs/2205.14756
• EfficientViT（MSRA） - https://arxiv.org/abs/2305.07027
• EVA - https://arxiv.org/abs/2211.07636
• EVA-02 - https://arxiv.org/abs/2303.11331
• FasterNet - https://arxiv.org/abs/2303.03667
• FastViT - https://arxiv.org/abs/2303.14189
• FlexiViT - https://arxiv.org/abs/2212.08013
• FocalNet（焦点调制网络） - https://arxiv.org/abs/2203.11926
• GCViT（全局上下文视觉Transformer） - https://arxiv.org/abs/2206.09959
• GhostNet - https://arxiv.org/abs/1911.11907
• GhostNet-V2 - https://arxiv.org/abs/2211.12905
• GhostNet-V3 - https://arxiv.org/abs/2404.11202
• gMLP - https://arxiv.org/abs/2105.08050
• GPU高效网络 - https://arxiv.org/abs/2006.14090
• Halo Nets - https://arxiv.org/abs/2103.12731
• HGNet / HGNet-V2 - 待定
• HRNet - https://arxiv.org/abs/1908.07919
• InceptionNeXt - https://arxiv.org/abs/2303.16900
• Inception-V3 - https://arxiv.org/abs/1512.00567
• Inception-ResNet-V2和Inception-V4 - https://arxiv.org/abs/1602.07261
• Lambda Networks - https://arxiv.org/abs/2102.08602
• LeViT（以卷积网络形式出现的视觉Transformer） - https://arxiv.org/abs/2104.01136
• MambaOut - https://arxiv.org/abs/2405.07992
• MaxViT（多轴视觉Transformer） - https://arxiv.org/abs/2204.01697
• MetaFormer（PoolFormer-v2、ConvFormer、CAFormer） - https://arxiv.org/abs/2210.13452
• MLP-Mixer - https://arxiv.org/abs/2105.01601
• MobileCLIP - https://arxiv.org/abs/2311.17049
• MobileNet-V3（带高效头部的MBConvNet） - https://arxiv.org/abs/1905.02244
  • FBNet-V3 - https://arxiv.org/abs/2006.02049
  • HardCoRe-NAS - https://arxiv.org/abs/2102.11646
  • LCNet - https://arxiv.org/abs/2109.15099
• MobileNetV4 - https://arxiv.org/abs/2404.10518
• MobileOne - https://arxiv.org/abs/2206.04040
• MobileViT - https://arxiv.org/abs/2110.02178
• MobileViT-V2 - https://arxiv.org/abs/2206.02680
• MViT-V2（改进型多尺度视觉Transformer） - https://arxiv.org/abs/2112.01526
• NASNet-A - https://arxiv.org/abs/1707.07012
• NesT - https://arxiv.org/abs/2105.12723
• Next-ViT - https://arxiv.org/abs/2207.05501
• NFNet-F - https://arxiv.org/abs/2102.06171
• NF-RegNet / NF-ResNet - https://arxiv.org/abs/2101.08692
• PE（感知编码器） - https://arxiv.org/abs/2504.13181
• PNasNet - https://arxiv.org/abs/1712.00559
• PoolFormer（MetaFormer） - https://arxiv.org/abs/2111.11418
• 基于池化的视觉Transformer（PiT） - https://arxiv.org/abs/2103.16302
• PVT-V2（改进型金字塔视觉Transformer） - https://arxiv.org/abs/2106.13797
• RDNet（重装版DenseNet） - https://arxiv.org/abs/2403.19588
• RegNet - https://arxiv.org/abs/2003.13678
• RegNetZ - https://arxiv.org/abs/2103.06877
• RepVGG - https://arxiv.org/abs/2101.03697
• RepGhostNet - https://arxiv.org/abs/2211.06088
• RepViT - https://arxiv.org/abs/2307.09283
• ResMLP - https://arxiv.org/abs/2105.03404
• ResNet/ResNeXt
  • ResNet（v1b/v1.5） - https://arxiv.org/abs/1512.03385
  • ResNeXt - https://arxiv.org/abs/1611.05431
  • “技巧包”/Gluon C、D、E、S变体 - https://arxiv.org/abs/1812.01187
  • 弱监督（WSL）Instagram预训练/ImageNet调优的ResNeXt101 - https://arxiv.org/abs/1805.00932
  • 半监督（SSL）/半弱监督（SWSL）ResNet/ResNeXts - https://arxiv.org/abs/1905.00546
  • ECA-Net（ECAResNet） - https://arxiv.org/abs/1910.03151v4
  • 挤压-激励网络（SEResNet） - https://arxiv.org/abs/1709.01507
  • ResNet-RS - https://arxiv.org/abs/2103.07579
• Res2Net - https://arxiv.org/abs/1904.01169
• ResNeSt - https://arxiv.org/abs/2004.08955
• ReXNet - https://arxiv.org/abs/2007.00992
• ROPE-ViT - https://arxiv.org/abs/2403.13298
• SelecSLS - https://arxiv.org/abs/1907.00837
• 选择性核网络 - https://arxiv.org/abs/1903.06586
• Sequencer2D - https://arxiv.org/abs/2205.01972
• SHViT - https://arxiv.org/abs/2401.16456
• SigLIP（图像编码器） - https://arxiv.org/abs/2303.15343
• SigLIP 2（图像编码器） - https://arxiv.org/abs/2502.14786
• StarNet - https://arxiv.org/abs/2403.19967
• SwiftFormer - https://arxiv.org/pdf/2303.15446
• Swin S3（AutoFormerV2） - https://arxiv.org/abs/2111.14725
• Swin Transformer - https://arxiv.org/abs/2103.14030
• Swin Transformer V2 - https://arxiv.org/abs/2111.09883
• TinyViT - https://arxiv.org/abs/2207.10666
• Transformer嵌套Transformer（TNT） - https://arxiv.org/abs/2103.00112
• TResNet - https://arxiv.org/abs/2003.13630
• Twins（视觉Transformer中的空间注意力） - https://arxiv.org/pdf/2104.13840.pdf
• VGG - https://arxiv.org/abs/1409.1556
• Visformer - https://arxiv.org/abs/2104.12533
• 视觉Transformer - https://arxiv.org/abs/2010.11929
• ViTamin - https://arxiv.org/abs/2404.02132
• VOLO（视觉展望者） - https://arxiv.org/abs/2106.13112
• VovNet V2和V1 - https://arxiv.org/abs/1911.06667
• Xception - https://arxiv.org/abs/1610.02357
• Xception（改良对齐版，Gluon） - https://arxiv.org/abs/1802.02611
• Xception（改良对齐版，TF） - https://arxiv.org/abs/1802.02611
• XCiT（交叉协方差图像Transformer） - https://arxiv.org/abs/2106.09681

Optimizers

To see full list of optimizers w/ descriptions: timm.optim.list_optimizers(with_description=True)

Included optimizers available via timm.optim.create_optimizer_v2 factory method:

• adabelief an implementation of AdaBelief adapted from https://github.com/juntang-zhuang/Adabelief-Optimizer - https://arxiv.org/abs/2010.07468
• adafactor adapted from FAIRSeq impl - https://arxiv.org/abs/1804.04235
• adafactorbv adapted from Big Vision - https://arxiv.org/abs/2106.04560
• adahessian by David Samuel - https://arxiv.org/abs/2006.00719
• adamp and sgdp by Naver ClovAI - https://arxiv.org/abs/2006.08217
• adamuon and nadamuon as per https://github.com/Chongjie-Si/AdaMuon - https://arxiv.org/abs/2507.11005
• adan an implementation of Adan adapted from https://github.com/sail-sg/Adan - https://arxiv.org/abs/2208.06677
• adopt ADOPT adapted from https://github.com/iShohei220/adopt - https://arxiv.org/abs/2411.02853
• kron PSGD w/ Kronecker-factored preconditioner from https://github.com/evanatyourservice/kron_torch - https://sites.google.com/site/lixilinx/home/psgd
• lamb an implementation of Lamb and LambC (w/ trust-clipping) cleaned up and modified to support use with XLA - https://arxiv.org/abs/1904.00962
• laprop optimizer from https://github.com/Z-T-WANG/LaProp-Optimizer - https://arxiv.org/abs/2002.04839
• lars an implementation of LARS and LARC (w/ trust-clipping) - https://arxiv.org/abs/1708.03888
• lion and implementation of Lion adapted from https://github.com/google/automl/tree/master/lion - https://arxiv.org/abs/2302.06675
• lookahead adapted from impl by Liam - https://arxiv.org/abs/1907.08610
• madgrad an implementation of MADGRAD adapted from https://github.com/facebookresearch/madgrad - https://arxiv.org/abs/2101.11075
• mars MARS optimizer from https://github.com/AGI-Arena/MARS - https://arxiv.org/abs/2411.10438
• muon MUON optimizer from https://github.com/KellerJordan/Muon with numerous additions and improved non-transformer behaviour
• nadam an implementation of Adam w/ Nesterov momentum
• nadamw an implementation of AdamW (Adam w/ decoupled weight-decay) w/ Nesterov momentum. A simplified impl based on https://github.com/mlcommons/algorithmic-efficiency
• novograd by Masashi Kimura - https://arxiv.org/abs/1905.11286
• radam by Liyuan Liu - https://arxiv.org/abs/1908.03265
• rmsprop_tf adapted from PyTorch RMSProp by myself. Reproduces much improved Tensorflow RMSProp behaviour
• sgdw and implementation of SGD w/ decoupled weight-decay
• fused<name> optimizers by name with NVIDIA Apex installed
• bnb<name> optimizers by name with BitsAndBytes installed
• cadamw, clion, and more 'Cautious' optimizers from https://github.com/kyleliang919/C-Optim - https://arxiv.org/abs/2411.16085
• adam, adamw, rmsprop, adadelta, adagrad, and sgd pass through to torch.optim implementations
• c suffix (eg adamc, nadamc to implement 'corrected weight decay' in https://arxiv.org/abs/2506.02285)

Augmentations

• Random Erasing from Zhun Zhong - https://arxiv.org/abs/1708.04896)
• Mixup - https://arxiv.org/abs/1710.09412
• CutMix - https://arxiv.org/abs/1905.04899
• AutoAugment (https://arxiv.org/abs/1805.09501) and RandAugment (https://arxiv.org/abs/1909.13719) ImageNet configurations modeled after impl for EfficientNet training (https://github.com/tensorflow/tpu/blob/master/models/official/efficientnet/autoaugment.py)
• AugMix w/ JSD loss, JSD w/ clean + augmented mixing support works with AutoAugment and RandAugment as well - https://arxiv.org/abs/1912.02781
• SplitBachNorm - allows splitting batch norm layers between clean and augmented (auxiliary batch norm) data

Regularization

• DropPath aka "Stochastic Depth" - https://arxiv.org/abs/1603.09382
• DropBlock - https://arxiv.org/abs/1810.12890
• Blur Pooling - https://arxiv.org/abs/1904.11486

Other

Several (less common) features that I often utilize in my projects are included. Many of their additions are the reason why I maintain my own set of models, instead of using others' via PIP:

• All models have a common default configuration interface and API for
  • accessing/changing the classifier - get_classifier and reset_classifier
  • doing a forward pass on just the features - forward_features (see documentation)
  • these makes it easy to write consistent network wrappers that work with any of the models
• All models support multi-scale feature map extraction (feature pyramids) via create_model (see documentation)
  • create_model(name, features_only=True, out_indices=..., output_stride=...)
  • out_indices creation arg specifies which feature maps to return, these indices are 0 based and generally correspond to the C(i + 1) feature level.
  • output_stride creation arg controls output stride of the network by using dilated convolutions. Most networks are stride 32 by default. Not all networks support this.
  • feature map channel counts, reduction level (stride) can be queried AFTER model creation via the .feature_info member
• All models have a consistent pretrained weight loader that adapts last linear if necessary, and from 3 to 1 channel input if desired
• High performance reference training, validation, and inference scripts that work in several process/GPU modes:
  • NVIDIA DDP w/ a single GPU per process, multiple processes with APEX present (AMP mixed-precision optional)
  • PyTorch DistributedDataParallel w/ multi-gpu, single process (AMP disabled as it crashes when enabled)
  • PyTorch w/ single GPU single process (AMP optional)
• A dynamic global pool implementation that allows selecting from average pooling, max pooling, average + max, or concat([average, max]) at model creation. All global pooling is adaptive average by default and compatible with pretrained weights.
• A 'Test Time Pool' wrapper that can wrap any of the included models and usually provides improved performance doing inference with input images larger than the training size. Idea adapted from original DPN implementation when I ported (https://github.com/cypw/DPNs)
• Learning rate schedulers
  • Ideas adopted from
    • AllenNLP schedulers
    • FAIRseq lr_scheduler
    • SGDR: Stochastic Gradient Descent with Warm Restarts (https://arxiv.org/abs/1608.03983)
  • Schedulers include step, cosine w/ restarts, tanh w/ restarts, plateau
• Space-to-Depth by mrT23 (https://arxiv.org/abs/1801.04590)
• Adaptive Gradient Clipping (https://arxiv.org/abs/2102.06171, https://github.com/deepmind/deepmind-research/tree/master/nfnets)
• An extensive selection of channel and/or spatial attention modules:
  • Bottleneck Transformer - https://arxiv.org/abs/2101.11605
  • CBAM - https://arxiv.org/abs/1807.06521
  • Effective Squeeze-Excitation (ESE) - https://arxiv.org/abs/1911.06667
  • Efficient Channel Attention (ECA) - https://arxiv.org/abs/1910.03151
  • Gather-Excite (GE) - https://arxiv.org/abs/1810.12348
  • Global Context (GC) - https://arxiv.org/abs/1904.11492
  • Halo - https://arxiv.org/abs/2103.12731
  • Involution - https://arxiv.org/abs/2103.06255
  • Lambda Layer - https://arxiv.org/abs/2102.08602
  • Non-Local (NL) - https://arxiv.org/abs/1711.07971
  • Squeeze-and-Excitation (SE) - https://arxiv.org/abs/1709.01507
  • Selective Kernel (SK) - (https://arxiv.org/abs/1903.06586
  • Split (SPLAT) - https://arxiv.org/abs/2004.08955
  • Shifted Window (SWIN) - https://arxiv.org/abs/2103.14030

Results

Model validation results can be found in the results tables

Getting Started (Documentation)

The official documentation can be found at https://huggingface.co/docs/hub/timm. Documentation contributions are welcome.

Getting Started with PyTorch Image Models (timm): A Practitioner’s Guide by Chris Hughes is an extensive blog post covering many aspects of timm in detail.

timmdocs is an alternate set of documentation for timm. A big thanks to Aman Arora for his efforts creating timmdocs.

paperswithcode is a good resource for browsing the models within timm.

Train, Validation, Inference Scripts

The root folder of the repository contains reference train, validation, and inference scripts that work with the included models and other features of this repository. They are adaptable for other datasets and use cases with a little hacking. See documentation.

Awesome PyTorch Resources

One of the greatest assets of PyTorch is the community and their contributions. A few of my favourite resources that pair well with the models and components here are listed below.

Object Detection, Instance and Semantic Segmentation

• Detectron2 - https://github.com/facebookresearch/detectron2
• Segmentation Models (Semantic) - https://github.com/qubvel/segmentation_models.pytorch
• EfficientDet (Obj Det, Semantic soon) - https://github.com/rwightman/efficientdet-pytorch

Computer Vision / Image Augmentation

• Albumentations - https://github.com/albumentations-team/albumentations
• Kornia - https://github.com/kornia/kornia

Knowledge Distillation

• RepDistiller - https://github.com/HobbitLong/RepDistiller
• torchdistill - https://github.com/yoshitomo-matsubara/torchdistill

Metric Learning

• PyTorch Metric Learning - https://github.com/KevinMusgrave/pytorch-metric-learning

Training / Frameworks

• fastai - https://github.com/fastai/fastai
• lightly_train - https://github.com/lightly-ai/lightly-train

Deployment

• timmx (Export timm models to ONNX, CoreML, LiteRT, TensorRT, and more) - https://github.com/Boulaouaney/timmx

Licenses

Code

The code here is licensed Apache 2.0. I've taken care to make sure any third party code included or adapted has compatible (permissive) licenses such as MIT, BSD, etc. I've made an effort to avoid any GPL / LGPL conflicts. That said, it is your responsibility to ensure you comply with licenses here and conditions of any dependent licenses. Where applicable, I've linked the sources/references for various components in docstrings. If you think I've missed anything please create an issue.

预训练权重

到目前为止，此处提供的所有预训练权重均是在 ImageNet 数据集上进行预训练的，其中仅有少数几个还进行了额外的预训练（详见下方的附加说明）。ImageNet 数据集仅面向非商业研究目的发布（https://image-net.org/download）。关于使用该数据集的预训练权重可能带来的法律影响尚不明确。我使用 ImageNet 训练的所有模型均出于研究目的，因此应假定原始数据集的许可协议同样适用于这些权重。如果您打算在商业产品中使用这些预训练权重，最好咨询法律意见。

不仅在 ImageNet 上预训练

此处包含或引用的若干权重是在我无法访问的专有数据集上进行预训练的。其中包括 Facebook 的 WSL、SSL、SWSL ResNe(Xt) 以及 Google 的 Noisy Student EfficientNet 模型。Facebook 的模型具有明确的非商业许可（CC-BY-NC 4.0，https://github.com/facebookresearch/semi-supervised-ImageNet1K-models，https://github.com/facebookresearch/WSL-Images）。而 Google 的模型似乎除了 Apache 2.0 许可证之外并无其他限制（当然也需考虑 ImageNet 相关问题）。无论哪种情况，如有任何疑问，您都应直接联系 Facebook 或 Google。

引用

BibTeX

@misc{rw2019timm,
  author = {Ross Wightman},
  title = {PyTorch 图像模型},
  year = {2019},
  publisher = {GitHub},
  journal = {GitHub 仓库},
  doi = {10.5281/zenodo.4414861},
  howpublished = {\url{https://github.com/rwightman/pytorch-image-models}}
}

最新 DOI

PyTorch Image Models (timm) 快速上手指南

pytorch-image-models (简称 timm) 是一个强大的 PyTorch 图像模型库，集成了数百种预训练的计算机视觉模型（如 ResNet, ViT, ConvNeXt 等），并提供统一的训练、验证和推理脚本。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python: 推荐 Python 3.10+ (支持范围通常为 3.8 - 3.13)
• PyTorch: 推荐 PyTorch 2.x (最低支持 1.13)
• GPU: 可选，但强烈推荐使用 NVIDIA GPU 以加速训练和推理

前置依赖检查： 请确保已正确安装 PyTorch 和 torchvision。您可以访问 PyTorch 官网 获取适合您环境的安装命令。

安装步骤

方式一：使用 pip 安装（推荐）

直接通过 PyPI 安装最新稳定版：

pip install timm

国内加速方案： 如果您在中国大陆，建议使用清华源或阿里源以加快下载速度：

pip install timm -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或者
pip install timm -i https://mirrors.aliyun.com/pypi/simple/

方式二：从源码安装（获取最新特性）

如果您需要使用 GitHub 上的最新代码（包含最新的模型和优化）：

pip install git+https://github.com/huggingface/pytorch-image-models.git

国内加速方案（源码）： 使用 Gitee 镜像或代理加速（如果可用），或者直接克隆后安装：

git clone https://gitee.com/mirrors/pytorch-image-models.git
cd pytorch-image-models
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

(注：Gitee 镜像地址需确认是否同步最新，若不可用请直接使用官方 git+https 配合网络代理)

基本使用

1. 加载预训练模型

这是最常用的功能。timm 允许您通过一行代码加载数千种架构及其预训练权重。

import torch
import timm

# 创建一个模型实例
# model_name: 模型名称，例如 'resnet50', 'vit_base_patch16_224', 'convnext_base'
# pretrained=True: 自动下载并加载 ImageNet 预训练权重
# features_only=False: 设置为 True 可仅提取中间特征层
model = timm.create_model('resnet50', pretrained=True)

# 将模型设置为评估模式
model.eval()

# 准备输入数据 (Batch Size=1, Channels=3, Height=224, Width=224)
input_tensor = torch.randn(1, 3, 224, 224)

# 前向传播
with torch.no_grad():
    output = model(input_tensor)

print(output.shape)  # 输出形状通常为 [batch_size, num_classes]

2. 查看可用模型

您可以列出所有支持的模型或搜索特定架构：

import timm

# 列出所有包含 'resnet' 的模型名称
models = timm.list_models('*resnet*')
print(models[:5])  # 打印前 5 个结果

# 获取特定模型的详细信息配置
config = timm.get_model_config('resnet50')
print(config)

3. 使用训练/验证脚本

timm 提供了功能完整的命令行脚本，用于训练、验证和批量推理。安装后，您可以在终端直接使用 train.py 和 validate.py（通常位于包内或通过 python -m timm 调用，具体取决于安装方式，建议参考官方文档获取最新脚本路径）。

一个简单的验证示例（假设已准备好 ImageNet 格式的数据集）：

# 使用预训练的 ResNet50 在验证集上进行评估
python validate.py /path/to/imagenet/val --model resnet50 --amp -j 8

• --amp: 启用自动混合精度加速推理。
• -j 8: 使用 8 个数据加载线程。

4. 提取特征（作为骨干网络）

如果您需要将模型作为其他任务（如检测、分割）的骨干网络：

import timm

# 创建模型并只返回特征层
model = timm.create_model('resnet50', pretrained=True, features_only=True)

# 此时 model 是一个 FeatureHookManager，forward 返回一个元组，包含各层特征
features = model(torch.randn(1, 3, 224, 224))

# features 是一个 tuple，包含不同分辨率的特征图
for i, f in enumerate(features):
    print(f"Layer {i} shape: {f.shape}")