Help#
Welcome to the Ultralytics Help page. This page brings together practical guides, policies, and FAQs to support your work with Ultralytics YOLO models and repositories.
- Frequently Asked Questions (FAQ): Find answers to common questions and issues encountered by the community of Ultralytics YOLO users and contributors.
- Contributing Guide: Discover the protocols for making contributions, including how to submit pull requests, report bugs, and more.
- Continuous Integration (CI) Guide: Learn about the CI processes we use, complete with status reports for each Ultralytics repository.
- Contributor License Agreement (CLA): Review the CLA to understand the rights and responsibilities associated with contributing to Ultralytics projects.
- Minimum Reproducible Example (MRE) Guide: Learn the process for creating an MRE, which is crucial for the timely and effective resolution of bug reports.
- Code of Conduct: Our community guidelines support a respectful and open atmosphere for all collaborators.
- Environmental, Health, and Safety (EHS) Policy: Learn about our commitment to sustainability and the well-being of all our stakeholders.
- Security Policy: Familiarize yourself with our security protocols and the procedure for reporting vulnerabilities.
- Privacy Policy: Read our privacy policy to understand how we protect your data and respect your privacy in all our services and operations.
We encourage you to review these resources for a smooth and productive experience. If you need additional support, reach out via GitHub Issues or the Ultralytics Community.
FAQ#
Ultralytics YOLO (You Only Look Once) is a state-of-the-art, real-time object detection model. Its latest version, YOLO26, delivers faster, lighter inference with an optional NMS-free end-to-end head, optimized for edge and low-power devices, making it well suited to a wide range of applications, from real-time video analytics to advanced machine learning research. YOLO's efficiency in detecting objects in images and videos has made it a popular choice for businesses and researchers looking to integrate robust computer vision capabilities into their projects.
For more details on the current release, visit the YOLO26 documentation. For the upcoming family, explore YOLO27 (Coming Soon); its models are not yet available and no launch date is set.
Contributing to Ultralytics YOLO repositories is straightforward. Start by reviewing the Contributing Guide to understand the protocols for submitting pull requests, reporting bugs, and more. You'll also need to sign the Contributor License Agreement (CLA) to ensure your contributions are legally recognized. For effective bug reporting, refer to the Minimum Reproducible Example (MRE) Guide.
Ultralytics Platform is a no-code solution for managing your machine learning projects. It lets you annotate data, train, and deploy models like YOLO26 in one place, with cloud training, live training metrics, and dataset management. It covers the full workflow, from data preparation to model deployment, for both beginners and advanced users.
To get started, visit Ultralytics Platform Quickstart.
Continuous Integration (CI) in Ultralytics involves automated processes that ensure the integrity and quality of the codebase. Our CI setup includes Docker deployment, broken link checks, CodeQL analysis, and PyPI publishing. These processes help maintain stable and secure repositories by automatically running tests and checks on new code submissions.
Learn more in the Continuous Integration (CI) Guide.
Ultralytics takes data privacy seriously. Our Privacy Policy outlines how we collect and use anonymized data to improve the YOLO package while prioritizing user privacy and control. We adhere to strict data protection regulations to keep your information secure.
Comments614
Ask a question, share your results, or help someone else.
si-open
please add a ruby gem for YOLO thanks
1yuchoyao
Hi Ultralytics team,
I have been trying to use YOLOv10 on the Windows platform these days, but unfortunately it has not been realized, because of a small problem I once encountered. I have searched for all similar problems, but their solution cannot solve my problem, I hope you can help me, thank you very much! I wrote a piece of Python code to use YOLOv10 for training, here is the code content, I am using the coco dataset
from ultralytics import YOLOv10 import supervision as sv import cv2 import os
classes = { 0: 'person', 1: 'bicycle', 2: 'car', 3: 'motorcycle', 4: 'airplane', 5: 'bus', 6: 'train', 7: 'truck', 8: 'boat', 9: 'traffic light', 10: 'fire hydrant', 11: 'stop sign', 12: 'parking meter', 13: 'bench', 14: 'bird', 15: 'cat', 16: 'dog', 17: 'horse', 18: 'sheep', 19: 'cow', 20: 'elephant', 21: 'bear', 22: 'zebra', 23: 'giraffe', 24: 'backpack', 25: 'umbrella', 26: 'handbag', 27: 'tie', 28: 'suitcase', 29: 'frisbee', 30: 'skis', 31: 'snowboard', 32: 'sports ball', 33: 'kite', 34: 'baseball bat', 35: 'baseball glove', 36: 'skateboard', 37: 'surfboard', 38: 'tennis racket', 39: 'bottle', 40: 'wine glass', 41: 'cup', 42: 'fork', 43: 'knife', 44: 'spoon', 45: 'bowl', 46: 'banana', 47: 'apple', 48: 'sandwich', 49: 'orange', 50: 'broccoli', 51: 'carrot', 52: 'hot dog', 53: 'pizza', 54: 'donut', 55: 'cake', 56: 'chair', 57: 'couch', 58: 'potted plant', 59: 'bed', 60: 'dining table', 61: 'toilet', 62: 'tv', 63: 'laptop', 64: 'mouse', 65: 'remote', 66: 'keyboard', 67: 'cell phone', 68: 'microwave', 69: 'oven', 70: 'toaster', 71: 'sink', 72: 'refrigerator', 73: 'book', 74: 'clock', 75: 'vase', 76: 'scissors', 77: 'teddy bear', 78: 'hair drier', 79: 'toothbrush' }
model = YOLOv10(r'D:\python3_12\yolov10-main\weights\yolov10b.pt')
image = cv2.imread("E:\coco_test_renamed")
results = model(source=image, conf=0.25, verbose=False)[0] detections = sv.Detections.from_ultralytics(results) box_annotator = sv.BoxAnnotator()
labels = [ f"{classes[class_id]} {confidence:.2f}" for class_id, confidence in zip(detections.class_id, detections.confidence) ] annotated_image = box_annotator.annotate( image.copy(), detections=detections, labels=labels )
cv2.imshow('result', annotated_image) cv2.waitKey() cv2.destroyAllWindows() cv2.imwrite('annotated_dog.jpeg', annotated_image)
After I run the code, the program will report an ERROR, thus terminating the run
D:\python3_12\Anaconda\anaconda3\envs\yolov10_torch\python.exe D:\python3_12\yolov10-main\test.py Traceback (most recent call last): File "D:\python3_12\yolov10-main\test.py", line 28, in image = cv2.imread("E:\coco_test_renamed") ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "D:\python3_12\yolov10-main\ultralytics\utils\patches.py", line 26, in imread return cv2.imdecode(np.fromfile(filename, np.uint8), flags) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PermissionError: [Errno 13] Permission denied: 'E:\coco_test_renamed'
Process finished with exit code 1
I have tried all methods to solve this problem without success, including changing file permissions on windows and using python to change file permissions and running pycharm with administrator permissions, but all have failed, especially since this problem only occurs when running YOLO.
If you can help me, I will appreciate it very much. Thank you very much.
1
Glenn JocherUltralyticsHi there,
Thank you for reaching out and providing detailed information about your issue. It looks like you're encountering a
PermissionErrorwhen trying to read the image file with OpenCV on your Windows platform.To help resolve this, please consider the following steps:
-
Verify File Path and Permissions: Ensure that the file path
"E:\\coco_test_renamed"is correct and that the file exists. Also, check the file permissions to make sure your script has read access to this file. -
Check File Path Format: Windows paths can sometimes be tricky. Try using raw strings or double backslashes to avoid escape character issues:
image = cv2.imread(r"E:\coco_test_renamed") -
Update Packages: Make sure you are using the latest versions of all relevant packages, including
ultralytics,supervision, andopencv-python. You can update them using pip:pip install --upgrade ultralytics supervision opencv-python -
Minimum Reproducible Example: If the issue persists, providing a minimum reproducible example can greatly help in diagnosing the problem. You can find guidance on creating one here: Minimum Reproducible Example Guide.
Here is a simplified version of your code to help isolate the issue:
import cv2 # Ensure the file path is correct and accessible image_path = r"E:\coco_test_renamed" image = cv2.imread(image_path) if image is None: print(f"Failed to load image from {image_path}") else: print("Image loaded successfully")Run this snippet to check if the image loads correctly. If it doesn't, the issue is likely with the file path or permissions.
Please try these steps and let us know if the problem persists. We're here to help!
3-
yuchoyao
Hi Thank you very much for your help.
After testing and adjusting the source code, I found that the real problem is not file permissions, but def imread(filename: str, flags: int = cv2.IMREAD_COLOR) This function can only accept a single image as the input parameter, and I wrote the file path as the folder path instead of the image path when I entered the parameter, so I caused a Permissionerror: [errno 13] permission denied ERROR. It is true that we should not only see the surface of ERROR but also understand the underlying causes of ERROR.
Thanks again for your help!
4
Glenn JocherUltralytics@YaoEndless hi there,
Thank you for the update and for identifying the root cause of the issue! It's great to hear that you were able to pinpoint the problem with the file path.
Indeed, the
cv2.imreadfunction expects a path to a single image file, not a directory. It's a common mistake, and your experience will certainly help others who might encounter a similar issue.If you have any further questions or run into other issues, feel free to reach out. We're here to help! For more detailed guidance on various topics, you can always refer to our Ultralytics Help page.
Happy coding! 😊
Juanrp7
Hola comunidad de Ultralytics, Estoy desarrollando un proyecto de detección y conteo de personas mediante cámaras CCTV utilizando el protocolo RTSP, orientado a generar analítica para varios centros comerciales con un total aproximado de 400 cámaras. Mi configuración actual es la siguiente:
Modelo: YOLOv11m GPU: NVIDIA RTX 4050 RAM: 64 GB CPU: Intel Core i5 de 12ª generación
Problema identificado: Al intentar procesar únicamente 3 streams RTSP de forma simultánea, el consumo de CPU se dispara de manera considerable, lo cual me preocupa de cara a escalar la solución. Tengo dos preguntas:
- ¿Por qué se dispara el consumo de CPU al procesar múltiples streams RTSP? ¿Es un problema relacionado con la decodificación de video, con la gestión de los streams, o con algún cuello de botella en la integración con YOLO? ¿Existe alguna configuración o práctica recomendada para mitigarlo?
- ¿Qué infraestructura recomiendan para escalar este proyecto a 400 cámaras? ¿Es más viable una solución on-premise con hardware dedicado, o convendría migrar a una infraestructura en la nube (AWS, GCP, Azure)? Agradezco cualquier referencia de arquitecturas similares que hayan implementado con Ultralytics YOLO a gran escala. Gracias de antemano por su ayuda.
Glenn JocherUltralyticsEl pico de CPU suele venir principalmente de la ingesta/decodificación RTSP (FFmpeg/OpenCV), buffering y preprocesado por stream, no del forward en GPU; al abrir varios RTSP a la vez se multiplican esos hilos de decodificación y la CPU se convierte en el cuello de botella aunque la inferencia vaya en la RTX. Para mitigarlo, normalmente ayuda bajar FPS efectivo y resolución (p. ej.
vid_stride+imgsz), usar modo multi-stream para procesar varios RTSP en un solo proceso, y asegurarte de iterar en streaming (generador) como en la guía de fuentes de inferencia (Stream y Multi-Stream); si además haces conteo con IDs, revisa Track mode porque el tracking añade carga extra.Para 400 cámaras, casi siempre termina siendo una arquitectura distribuida (varios nodos) y dimensionada por “cámaras × FPS objetivo × resolución”: on‑prem cerca de las cámaras suele ser más viable por ancho de banda y latencia, y un enfoque híbrido (edge para inferir + cloud para eventos/métricas) suele escalar mejor; como referencia de decisiones/criterios, mira buenas prácticas de despliegue y el artículo sobre edge vs cloud para desplegar YOLO26. Si compartes resolución/codec (H.264/H.265), FPS de cámara, FPS objetivo por stream y el comando/código exacto que usas, puedo ayudarte a estimar capacidad por GPU y dónde se está yendo la CPU.
Juanrp7
Hola Glenn, Muchas gracias por tu respuesta. Quisiera compartir una actualización y ampliar un poco el contexto. Después de realizar algunos ajustes en el código, logré reducir el consumo de CPU aproximadamente en un 70%, lo cual fue una mejora importante. Sin embargo, como mencioné en la publicación inicial, actualmente estoy realizando pruebas únicamente con 3 cámaras RTSP. Aunque el consumo de CPU disminuyó considerablemente, la precisión del conteo también bajó, situándose ahora entre 30% y 40%. Mi objetivo es alcanzar al menos una precisión del 80%–90%. En este punto, me gustaría entender mejor:- ¿Cuántas cámaras puede soportar mi arquitectura actual manteniendo un buen rendimiento y una precisión aceptable?
- ¿Cuál sería la arquitectura ideal para desplegar entre 5 y 10 cámaras con una precisión cercana al 90%?
Infraestructura actual- GPU: NVIDIA RTX 4050 (6GB VRAM)
- RAM: 64 GB
- CPU: Intel Core i5 (12ª generación)
- Sistema operativo: Ubuntu Server
📊 Configuración actual de cámaras (Etapa 1 – 3 cámaras)Cámara Resolución Codec FPS Cámara vid_stride FPS procesado aprox. Costa 740×480 H.265 30 3 ~10 FPS Tomaticos 740×480 H.264 30 3 ~6.7 FPS Supermercado 740×480 H.265 30 3 ~10 FPS
🖥 Arquitectura actual de despliegue Servidor Linux (147.xxx.x.xxx) ┌──────────────────────────────────────────── │ SERVIDOR LINUX (147.XXX.X.XXX) │ │ launcher.py (supervisor) │ ├── conteo_entrada_costa_v2.py → :8081/stream │ ├── conteo_tomaticos_lineas.py → :8082/stream │ └── supermercado.py → :8083/stream │ │ Cada proceso ejecuta: │ RTSP 704×480 → YOLO11n (GPU) → ByteTrack → MJPEG HTTP └──────────────────────────────────────────── Cliente (PC Windows) HTTP (puertos 8081–8083) ▼ ┌──────────────────────────────────────────── │ PC Windows │ → dashboard.html (visualiza las 3 cámaras) └──────────────────────────────────────────── Actualmente, cada cámara se ejecuta en un proceso Python independiente, y cada uno realiza:- Ingesta RTSP
- Inferencia con YOLO11n en GPU
- Tracking con ByteTrack
- Publicación vía MJPEG sobre HTTP
📍 Próxima etapa – Escalamiento En una segunda fase, el objetivo es desplegar la solución en uno de los 8 centros comerciales, el cual cuenta con aproximadamente 100–150 cámaras. Antes de avanzar hacia esa etapa, me gustaría conocer su recomendación sobre:- Número estimado de cámaras que puede soportar una GPU bajo esta configuración.
- Si utilizar modo multi-stream en un solo proceso mejoraría significativamente la eficiencia frente al modelo actual de procesos independientes.
- Buenas prácticas para mantener una precisión cercana al 90% al escalar.
- Arquitectura recomendada para 5–10 cámaras con alta precisión.
- Arquitectura distribuida sugerida para un escenario de 100–150 cámaras.
Código Fuente
El código fuente y la implementación actual pueden consultarse en:
Glenn JocherUltralyticsLa bajada de precisión casi siempre viene de que al recortar carga (p. ej., subir
vid_stridey/o bajar FPS efectivo) el tracking se vuelve inestable: ByteTrack pierde asociaciones/IDs y los cruces de línea dejan de contarse bien, así que para llegar a 80–90% normalmente necesitas mantener más “densidad temporal” (más frames útiles) y recortar CPU por otro lado, idealmente usando el substream de la cámara (misma escena pero menor bitrate/resolución) y/o decodificación acelerada en lugar de saltarte tantos frames; también ayuda ajustar el YAML del tracker a tu escena (umbral de matching/buffer, etc.) partiendo de los configs en el directorio de trackers.Sobre capacidad, con una RTX 4050 de 6GB el límite suele ser la ingesta/decodificación + tracking (y el MJPEG también consume CPU), no tanto la inferencia; si consigues decodificar “barato” y usas un modelo ligero (te recomendaría probar Ultralytics YOLO con
yolo26n.pt/yolo26s.pt), 5–10 cámaras a 480p con FPS moderado suele ser alcanzable, pero la forma fiable de estimarlo es medir 1 cámara y escalar hasta saturar CPU/GPU (porque depende mucho de cuánta gente haya en escena y del codec H.265 vs H.264).Si compartes en texto (sin HTML) el comando exacto y la parte mínima del pipeline de tu repo repositorio
analiticamque reproduce el conteo, junto con la salida deyolo checks, podemos afinar el dimensionamiento y ver si tienes cuellos por múltiples instalaciones/rutas (guía útil: Troubleshooting Common YOLO Issues).
Bill StrumGot it working, I have a path issue in PCharm that I have to track down
Thanks
On Sat, Feb 21, 2026 at 4:23 PM Glenn Jocher @.***> wrote:
This usually means a version/path mismatch: the yolo26m-seg.pt checkpoint was saved with a build that includes Segment26, but the ultralytics you’re importing in that conda env doesn’t (or you have multiple installs shadowing each other), so please upgrade, restart Python, then paste the text output from yolo checks and the full traceback if it still fails (see the Troubleshooting Common YOLO Issues https://docs.ultralytics.com/guides/yolo-common-issues/ guide for common env conflicts).
pip install -U ultralytics yolo checks
import ultralyticsprint(ultralytics.version)print(ultralytics.file)
— Reply to this email directly, view it on GitHub https://github.com/orgs/ultralytics/discussions/8027#discussioncomment-15884673, or unsubscribe https://github.com/notifications/unsubscribe-auth/AI2XRUL3AMQKVRTST64HVST4NDEELAVCNFSM6AAAAABCZTU2BOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKOBYGQ3DOMY . You are receiving this because you commented.Message ID: @.*** com>
Glenn JocherUltralyticsGlad you got it working — in PyCharm this is almost always the Run/Debug “Python interpreter” pointing to a different env than your terminal, so please double-check
sys.executableand thatultralytics.__file__resolves inside the same conda env/site-packages (and if it doesn’t, runultralytics.utils.checks.check_multiple_install()to catch shadowed installs); the env-conflict patterns are also covered in the Troubleshooting Common YOLO Issues guide.import sys, ultralytics print(sys.executable) print(ultralytics.__version__) print(ultralytics.__file__)
Bill StrumI am getting this error when trying to run YOLO using model yolo26m-seg
AttributeError: Can't get attribute 'Segment26' on <module 'ultralytics.nn.modules.head' from 'C:\Users\User\.conda\envs\AI_Test\Lib\site-packages\ultralytics\nn\modules\head.py'>
I'm using version: Ultralytics version: 8.3.169
Here is the code 👍 import ultralytics from ultralytics import YOLO
print(f"Ultralytics version: {ultralytics.version}")
model = YOLO("yolo26m-seg.pt")
Use one-to-one head (default, no NMS required)
#results = model.predict("images/dog.jpg", conf=0.15) results = model.predict("images/mixed_traffic_1.jpg", conf=0.1)
Display the result
for result in results: result.show()
Please advise on problem fix.
CB BIll
Glenn JocherUltralyticsThis usually means a version/path mismatch: the
yolo26m-seg.ptcheckpoint was saved with a build that includesSegment26, but theultralyticsyou’re importing in that conda env doesn’t (or you have multiple installs shadowing each other), so please upgrade, restart Python, then paste the text output fromyolo checksand the full traceback if it still fails (see the Troubleshooting Common YOLO Issues guide for common env conflicts).pip install -U ultralytics yolo checksimport ultralytics print(ultralytics.__version__) print(ultralytics.__file__)
nono2512
YOLO26n OpenVINO export segfaults on Intel N100 GPU
- Hardware: Intel N100 (Alder Lake-N, UHD Graphics)
- OS: Ubuntu 24.04, LXC
- OpenVINO: 2025.4.1
- Ultralytics: 8.4.14
- Drivers: intel-compute-runtime 26.05
GPU works with Intel models (person-detection-0202) but segfaults on YOLO26n_openvino_model with device="intel:gpu"
995742853
Hi. I noticed in ultralytics/utils/torch_utils.py, the initialize_weights function sets eps=0.001 and momentum=0.03 for BatchNorm2d layers, instead of the PyTorch defaults.
Could you briefly explain the reasoning behind these values? Do they significantly improve model performance or robustness?
Thanks!
Glenn JocherUltralyticsThose BatchNorm2d settings (
eps=1e-3,momentum=0.03) are a long-standing YOLO training convention rather than a random tweak: the slightly largerepsis mainly for numerical stability (especially with mixed precision and aggressive augmentations), and the lowermomentummakes the running mean/var update more smoothly (less noisy), which can help robustness when batch composition varies. In practice they rarely “unlock” big mAP gains by themselves, but they tend to reduce edge-case instability and keep training behavior consistent across YOLO models; see the background in our Batch Normalization overview.995742853
Thank you for your reply. Wish you a wonderful day!
keykin
Hi, how to install ultralytics without deps matplotlib, because armbian can not run pip with --no-deps but can only run pipx without --no-deps. Is there any packages or CLI commands can be used? Thanks a lot.
keykin
I have found a way by modifying the pyproject.toml and executing pipx install.
Glenn JocherUltralytics@elsaoreen if you’ve already exported to NCNN, you can load the exported
*_ncnn_modelfolder withYOLO(...)and pass Picamera2 frames (asnp.ndarray) directly; see the NCNN integration guide for the expected export/load workflow.from picamera2 import Picamera2 import cv2 from ultralytics import YOLO model = YOLO("yolo26n_ncnn_model") # path to exported NCNN model folder picam2 = Picamera2() picam2.configure(picam2.create_preview_configuration(main={"format": "RGB888"})) picam2.start() while True: frame = picam2.capture_array() # RGB frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR) # Ultralytics/OpenCV-friendly _ = model.predict(source=frame, imgsz=640, conf=0.25, verbose=False)@keykin
matplotlibis currently a required dependency inultralytics, so “no-matplotlib” installs aren’t officially supported, but if you want to avoid editingpyproject.toml,pipxcan pass through--no-depsvia--pip-argsand then you can selectively add packages withpipx inject(see pipx install docs and the pipx inject examples).pipx install ultralytics --pip-args="--no-deps" pipx inject ultralytics numpy opencv-python pillow pyyaml requests scipy
elsaoreen
I am having trouble integrating the code to run YOLO NCNN model with picamera2 module.
LJY886321
onnx输出的[1,6,8400],中的6是包含一个类别数吗,为什么我的pt文件是两个类别,而onnx总是一个类别数呢
Glenn JocherUltralytics[1, 6, 8400]里这个6通常不是“只有 1 个类别”,而是4 + nc:前 4 个通道是框坐标,后nc个通道是每个类别的分数;所以当6=4+2时,恰好表示你的模型是 2 类(与你的pt一致),只是导出后的张量结构里没有单独的 objectness 通道(端到端/NMS-free 头一般用 per-class score 形式)。相关输出说明见导出模型的输出张量说明。如果你愿意,把你的导出命令(是否带了nms=True)和 ONNX 的输出节点名贴在这里,我可以帮你对齐后处理的维度/转置方式。