ultralytics 8.4.49

v8.4.49 - `ultralytics 8.4.49` Fail fast on three common training failure modes (#24478)

on Python PyPI

🌟 Summary

Ultralytics v8.4.49 is mainly a stability and usability release 🛠️—it helps training fail earlier with clearer messages, recovers from corrupted cached weights automatically, and includes several quality-of-life fixes across training, metrics, benchmarking, tuning, tracking, and docs.

📊 Key Changes

• 🚨 Fail-fast training improvements from PR #24478 by @glenn-jocher:

  • Corrupt cached model files now recover automatically: if a cached .pt weight file is damaged or incomplete, Ultralytics now deletes it and re-downloads it instead of failing repeatedly.
  • Clear error when everything is frozen: if freeze is set too high and no trainable parameters remain, training now stops immediately with a direct, understandable error.
  • Clear error for empty classification splits: if class filtering leaves a train/val split with zero images, users now get a helpful FileNotFoundError naming the empty split.

• 🧠 Better distributed training behavior with torch.compile from PR #24413 by @Y-T-G:

  • DDP setup was adjusted to improve compatibility and stability, especially for compiled models and edge cases like batches with no labels.

• 📈 Per-image F1 metric fix from PR #24444 by @fcakyon:

  • Images with no ground-truth objects and no predictions are now scored correctly as a perfect result rather than an F1 of 0.

• 🧪 Hyperparameter tuning randomness fix from PR #24451 by @raimbekovm:

  • The tuner no longer risks repeating the same mutations in very fast iterations, improving search diversity.

• 🛤️ Dataset relative path handling fix from PR #24429 by @auduntorp:

  • Relative paths like ../ are now handled correctly in dataset file lists.

• ⚙️ Benchmarking fix from PR #24450 by @Y-T-G:

  • Prevents the data argument from being incorrectly forwarded into export benchmarking flows.

• 🎯 Tracker API cleanup from PR #24457 by @Laughing-q:

  • Removed the unused frame_rate argument from BYTETracker and BOTSORT, making tracker setup simpler.

• 🚀 CI / runner updates from PR #24436 by @glenn-jocher:

  • Updated runner images and improved TensorRT package caching for smoother CI performance.

• 📚 Docs and reference improvements:

  • Added a proper Python API reference landing page, fixed broken links, improved docs formatting, clarified prediction behavior, and polished several guides.

🎯 Purpose & Impact

• 💸 Saves GPU time and debugging effort: the biggest win in this release is that common training failures are caught before they waste compute or crash later with confusing PyTorch errors.
• 🔁 More self-healing behavior: corrupted cached weights no longer create a “stuck” failure state across repeated runs.
• 🧩 Better error messages for real-world dataset issues: users should spend less time guessing whether a problem is caused by freezing too much, bad caches, or empty class-filtered datasets.
• 🤖 More reliable advanced training setups: users training with DDP, torch.compile, or hyperparameter evolution should see fewer odd edge-case failures.
• 📊 More accurate evaluation reporting: the F1 fix makes validation metrics more fair in empty-image cases.
• 🛠️ Small but practical developer improvements: cleaner tracker initialization, safer benchmarking behavior, and better dataset path handling reduce friction in day-to-day use.
• 📘 Smoother docs experience: while not a model update, the documentation cleanup should make navigation and setup easier for everyone.

Overall, v8.4.49 is less about new models and more about making Ultralytics training and evaluation more robust, more predictable, and easier to troubleshoot ✅

What's Changed

• Support relative paths including ../ by @auduntorp in #24429
• Update runner images and cache TensorRT by @glenn-jocher in #24436
• Use static_graph=True for compile and remove find_unused_parameters by @Y-T-G in #24413
• docs: Add configurable gradient clipping example to custom trainer guide by @artest08 in #24420
• docs: Add Reference section landing page (/reference/index.md) by @glenn-jocher in #24443
• Docs: clarify rect and tuple imgsz for predict (#24440) by @AffanBinFaisal in #24441
• Fix broken docs links by @glenn-jocher in #24448
• Fix duplicate data argument in benchmark call by @Y-T-G in #24450
• Fix per-image F1 for empty-GT empty-pred images by @fcakyon in #24444
• docs: Add RT-DETR variant to per-layer learning rates guide by @artest08 in #24419
• docs: fix banner, admonition image, and stacked badges by @glenn-jocher in #24456
• Bump urllib3 from 2.6.3 to 2.7.0 in /examples/RTDETR-ONNXRuntime-Python in the pip group across 1 directory by @dependabot[bot] in #24460
• Update URLs to follow 301 redirects to final destinations by @glenn-jocher in #24462
• Professionalize YOLOv5 tutorials by @glenn-jocher in #24468
• Fix Tuner._mutate RNG collisions for sub-second iterations by @raimbekovm in #24451
• Remove unused frame_rate in BYTETracker/BOTSORT by @Laughing-q in #24457
• Fix docs language banner links by @glenn-jocher in #24474
• docs: add export install tip for benchmarks by @banu4prasad in #24464
• Remove flaky DOI badges from docs badge arrays by @glenn-jocher in #24476
• ultralytics 8.4.49 Fail fast on three common training failure modes by @glenn-jocher in #24478

New Contributors

• @AffanBinFaisal made their first contribution in #24441
• @auduntorp made their first contribution in #24429

Full Changelog: v8.4.48...v8.4.49