ultralytics 8.4.90

v8.4.90 - Add YOLO architecture explained guide (#24970)

on Python PyPI

🌟 Summary

Ultralytics v8.4.90 adds a major new YOLO Architecture Explained guide for understanding the evolution from YOLOv3 to YOLO26, while also improving tracking reliability, segmentation edge-case handling, Docker GPU guidance, and contributor workflows 🚀📚

📊 Key Changes

• 🧠 New YOLO Architecture Explained guide

  • Added a detailed documentation page explaining how Ultralytics YOLO architectures evolved from YOLOv3 → YOLOv5 → YOLOv8 → YOLO11 → YOLO26.
  • Covers the major building blocks across the backbone, neck, and detection head, including Bottleneck, C3, C2f, C3k2, SPPF, C2PSA, DFL, anchor-free detection, and YOLO26’s NMS-free / DFL-free design.
  • Includes stage-level Mermaid diagrams, model inspection details, and links to the relevant YAML configs and module definitions.
  • Registered in mkdocs.yml and the guides index for easier discovery.
  • Contributed by @raimbekovm.

• 🎯 Improved ByteTrack and FastTrack low-confidence recovery

  • Fixed second-stage association in BYTETracker and FastTracker so low-confidence detections can correctly recover existing tracks when fuse_score=True.
  • The second association now uses IoU-only matching, matching ByteTrack’s intended behavior for low-score detections.
  • Added tests to confirm low-confidence detections keep the same track ID.

• 🧩 Segmentation mask utilities now handle zero detections

  • Fixed process_mask, process_mask_native, and scale_masks for valid empty inputs with zero detections.
  • These functions now return correctly shaped empty tensors instead of crashing.
  • Simplified segmentation validation postprocessing to rely on the shared utility behavior.

• 🐳 Docker GPU examples updated to CDI device requests

  • Replaced legacy --runtime=nvidia --gpus all examples with modern CDI-style device requests such as --device nvidia.com/gpu=all.
  • Updated Dockerfiles, quickstarts, Triton docs, DGX Spark docs, and YOLOv5 Docker documentation.
  • Added guidance that CDI requires Docker >= 28.2.0 and NVIDIA Container Toolkit >= 1.18, with legacy flags still noted for older systems.

• 🤖 New AI-agent contributor guidance

  • Added AGENTS.md with repository overview, engineering principles, development commands, PR workflow expectations, and architecture notes.
  • Added CLAUDE.md as a symlink for Claude Code compatibility.
  • Helps AI coding agents and contributors work more consistently in the Ultralytics repository.

• 🔇 Cleaner safe-load behavior

  • Removed an unnecessary warning when restricted model loading is unavailable on older PyTorch versions.
  • Reduces log noise without changing model loading behavior.

• 🧪 CI compatibility fix

  • Pinned NumPy <2 for the PyTorch 2.3.0 / torchvision 0.18.0 slow-test shard to avoid a known ColorJitter hue overflow issue.
  • Improves CI stability for legacy dependency combinations.

• 🔗 Documentation link updates and cleanup

  • Updated renamed Ultralytics solutions URLs from old ai-in-* paths to new computer-vision-in-* paths.
  • Cleaned up SolutionResults docs table formatting.
  • Simplified Roboflow-100 docs example by importing Roboflow directly and clarifying API key requirements.
  • Added contributor attribution for SuperMarioYL.

🎯 Purpose & Impact

• 📚 Easier learning and model understanding

  • The new architecture guide makes YOLO’s evolution easier to understand for both researchers and practical users.
  • Users can better see why YOLO26 is faster and simpler at deployment, especially with its end-to-end, NMS-free detection design.

• 🚀 More reliable object tracking

  • Tracking applications such as traffic analytics, sports analysis, retail monitoring, and security systems should better preserve object IDs when detections briefly drop in confidence.

• ✅ More robust segmentation workflows

  • Developers manually using mask post-processing utilities, especially with exported models, can now safely process frames where no objects are detected.

• 🐳 More stable GPU containers

  • CDI-based Docker examples help long-running GPU workloads, CI runners, and training containers keep GPU access more reliably across host system reloads.

• 🤝 Better contributor and automation support

  • AGENTS.md gives human contributors and AI coding tools clearer expectations, helping future PRs stay consistent, tested, and maintainable.

• 🧹 Smoother user experience

  • Reduced warnings, cleaner docs, updated links, and improved tests make the package easier to use, maintain, and troubleshoot.

What's Changed

• Silence safe load fallback warning by @glenn-jocher in #25033
• Add AGENTS.md agent guidance with CLAUDE.md symlink by @glenn-jocher in #25035
• Lead AGENTS.md with repository overview by @glenn-jocher in #25036
• Fix ByteTrack second association ignoring low-confidence detections with fuse_score=True by @JESUSROYETH in #25034
• Fix process_mask, process_mask_native and scale_masks on empty 0-detection inputs by @JESUSROYETH in #25032
• fix(ci): pin NumPy <2 for torch 2.3.0 / torchvision 0.18.0 SlowTests shard by @onuralpszr in #25037
• docs: update links to renamed solution pages by @miles-deans-ultralytics in #25039
• Replace legacy --gpus examples with CDI device requests across docs and Dockerfiles by @glenn-jocher in #25040
• Add YOLO architecture explained guide by @raimbekovm in #24970

Full Changelog: v8.4.89...v8.4.90