RF-DETR Files

🌱 Changed

• Class names on predictions. predict() now includes class_name in the returned detections.data dict, mapping each detection's 0-indexed class ID to its human-readable name. No more manual lookups. (#914)

  python model = RFDETRSmall(pretrain_weights="path/to/fine_tuned.pth") detections = model.predict("image.jpg", threshold=0.5) print(detections.data["class_name"]) # ["cat", "dog", "cat"]

🔧 Fixed

• Fixed segmentation training crashing on multi-GPU DDP setups. The segmentation head leaves some parameters unused on certain forward steps, which triggered RuntimeError: parameters that were not used in producing the loss. build_trainer() now automatically enables find_unused_parameters=True when segmentation_head=True. (#947)

• Fixed fused AdamW optimizer crash during FP32 multi-GPU training. On Ampere+ GPUs, fused AdamW was enabled whenever the hardware supported BF16 — even when the trainer was explicitly configured for precision="32-true". This caused a dtype mismatch in DDP gradient buckets. The optimizer now checks the trainer's actual precision setting, not just GPU capability. (#947)

• Fixed multi-GPU DDP training failing in Jupyter notebooks and Kaggle. Fork-based DDP corrupted PyTorch's OpenMP thread pool, causing SIGABRT on the second process. RF-DETR now uses a spawn-based DDP strategy in interactive environments, avoiding the thread pool issue entirely. (#928)

• Fixed RFDETR.train(resolution=...) being silently ignored. The resolution kwarg is a model-level setting, not a training config field, so it was quietly dropped. It is now applied to the model config before training begins, with validation that the value is divisible by patch_size * num_windows. (#933)

  python model = RFDETRSmall() model.train(dataset_dir="./dataset", resolution=768) # now works

• Fixed save_dataset_grids being silently a no-op. The grid saver was never wired into the training loop. Dataset sample grids are now saved to {output_dir}/dataset_grids/ when enabled. Grid save failures are caught and logged without interrupting training. (#946)

• Fixed partial gradient-accumulation windows at the end of training epochs. When the dataset length was not evenly divisible by effective_batch_size * world_size, PyTorch Lightning would fire the optimizer on an incomplete accumulation window. The training dataset is now padded to an exact multiple, ensuring every optimizer step uses a full gradient window. (#937)

• Fixed torch.export.export failing on the transformer decoder. The spatial_shapes_hw parameter was not threaded through the decoder layers, breaking export for models using multi-scale deformable attention. (#936)

• Fixed download_pretrain_weights() silently overwriting fine-tuned checkpoints. When a fine-tuned checkpoint shared a filename with a registry model (e.g. rf-detr-nano.pth), an MD5 mismatch would trigger a re-download that replaced the user's weights. The function now returns early when the file exists and redownload=False, emitting a warning instead. (#935)

🏆 Contributors

Welcome to our new contributors, and thank you to everyone who helped with this release:

• M. Fazri Nizar (@mfazrinizar) (LinkedIn) — multi-GPU DDP training in notebooks
• Jiahao Sun (@sjhddh) (LinkedIn) — config type hint fix
• Jirka Borovec (@Borda) (LinkedIn) — release coordination, reviews

Automated contributions: @copilot-swe-agent[bot], @pre-commit-ci[bot]

Full changelog: https://github.com/roboflow/rf-detr/compare/1.6.3...1.6.4