[EHxuban11]

Newcomers and coding agents often arrive with Ultralytics habits and hit dead ends with no hint of what to type instead. This turns the most common ones into errors that name the LibreYOLO equivalent.

Changes

• from libreyolo import YOLO (also RTDETR, NAS, YOLOWorld, YOLOE, SAM) raises an ImportError that shows the LibreYOLO import and a one-line example. Plain attribute access still raises AttributeError, so hasattr() is unchanged.
• Ultralytics weight names (yolov8n.pt, yolo11s-seg.pt, v3u/v5/v8/v9/v10/11/12/26, -seg/-pose/-obb/-cls/-world, yoloe-*, yolo_nas_*, model .yaml, misspellings like yolov11n) now say it is an Ultralytics name, that LibreYOLO does not load Ultralytics weights, and suggest the closest LibreYOLO model. Every suggested file is checked against the model registry in tests.
• Ultralytics-trained checkpoints (best.pt) are detected without unpickling and refused with a "train a LibreYOLO model on your data" hint, instead of torch's weights_only=False advice.
• Same hints in the CLI (predict, train, val, export, quantize, info).
• predict() options project, name, tracker, persist, save_txt, save_conf name the LibreYOLO equivalent.
• Fix: LibreYOLO("yolov8n") no longer suggests a nonexistent hf://weights/yolov8n path.

No Ultralytics name becomes an alias, and nothing loads or converts Ultralytics weights.

Tests

tests/unit/test_ultralytics_hints.py (about 60 cases) plus a torch-free import test. Locally with pytest -n 4: new tests, tests/unit/cli and related loading tests pass.

Code provenance

Original code written for this PR. No code ported or adapted from other repositories.

Confidence Score: 5/5

The PR appears safe to merge, with a non-blocking correction needed in the classification training hint.

Findings

1.  Classification hint suggests unsupported YAML ▶

Summary

Adds errors that show LibreYOLO alternatives for unsupported Ultralytics imports, model names, checkpoints, and prediction options.

• Python imports of Ultralytics class names now show the LibreYOLO import.
• Ultralytics model names now point to the closest LibreYOLO model or training command.
• Ultralytics checkpoints now explain how to train with LibreYOLO instead.
• Unsupported prediction options now name the LibreYOLO way to do the same job.

_{Reviews (3) · Last reviewed commit: "Untrained-model hints train with pretrai..." · Reviewed by Greptile}

[greptile-apps]

Classification hint suggests unsupported YAML

For classification names such as yolov8m-cls.yaml, the new training step suggests data="your_data.yaml". But LibreMobileNetV4.train() accepts a dataset directory, a known dataset name, or a ZIP URL, not a dataset YAML file. Users who substitute their own YAML file get another error instead of starting training. Use a classification dataset directory in this hint.