Ultralytics YOLO27: Join the waitlist.
Get Started

Comprehensive Tutorials for Ultralytics YOLO#

Ultralytics YOLO guides cover every stage of a vision AI project, from training and prediction to deployment. Built on PyTorch, YOLO combines speed and accuracy for real-time object detection and other vision tasks.

Whether you're a beginner or an expert in deep learning, these tutorials offer practical guidance on implementing and optimizing YOLO for your computer vision projects.



Watch: Ultralytics YOLO26 Guides Overview

Guides#

Guides are grouped by project stage — from environment setup and data preparation through training, evaluation, deployment, inference optimization, and edge hardware — so you can jump straight to the step you're working on.

Get started & plan#

  • Conda Quickstart: Step-by-step guide to setting up a Conda environment for Ultralytics. Learn how to install and start using the Ultralytics package efficiently with Conda.
  • Docker Quickstart: Complete guide to setting up and using Ultralytics YOLO models with Docker. Learn how to install Docker, manage GPU support, and run YOLO models in isolated containers for consistent development and deployment.
  • AzureML Quickstart: Get up and running with Ultralytics YOLO models on Microsoft's Azure Machine Learning platform. Learn how to train, deploy, and scale your object detection projects in the cloud.
  • Modal Quickstart: Run Ultralytics YOLO26 on Modal's serverless cloud platform, covering authentication, GPU inference, and training jobs with persistent storage — no infrastructure to manage.
  • Defining A Computer Vision Project's Goals: Walk through how to effectively define clear and measurable goals for your computer vision project. Learn the importance of a well-defined problem statement and how it creates a roadmap for your project.
  • Steps of a Computer Vision Project: Learn about the key steps involved in a computer vision project, including defining goals, selecting models, preparing data, and evaluating results.
  • YOLO Architecture Explained: Trace how the YOLO architecture evolved from YOLOv3 to YOLO26 across backbone, neck, and detection head, covering C2f, C3k2, C2PSA attention, anchor-free, and NMS-free design.

Prepare your data#

  • Data Collection and Annotation: Explore the tools, techniques, and best practices for collecting and annotating data to create high-quality inputs for your computer vision models.
  • Preprocessing Annotated Data: Learn data preprocessing for computer vision with YOLO26, including image resizing, normalization, dataset splitting, data augmentation, and exploratory data analysis (EDA).
  • YOLO Data Augmentation: Explore the full range of data augmentation techniques in YOLO, from basic transformations to advanced strategies for improving model robustness and performance.
  • COCO to YOLO Conversion: Complete guide to converting COCO JSON annotations to YOLO format for training. Covers detection, segmentation, and keypoints, including class ID mapping and common conversion pitfalls.
  • COCO JSON Training: Train YOLO directly on COCO JSON annotations without converting to YOLO format, using a custom dataset class and trainer.

Train & fine-tune#

  • Tips for Model Training: Explore tips on optimizing batch sizes, using mixed precision, applying pretrained weights, and more to train computer vision models more effectively.
  • Fine-Tuning YOLO on Custom Data: Complete guide to fine-tuning YOLO26 on custom datasets with pretrained weights, covering transfer learning, layer freezing, optimizer selection, two-stage training, and troubleshooting.
  • YOLO26 Training Recipe: Full documentation of the hyperparameters, augmentation pipelines, and optimizer settings used to train the official YOLO26 base checkpoints on COCO, with practical fine-tuning guidance.
  • Hyperparameter Tuning: Discover how to optimize your YOLO models by fine-tuning hyperparameters using the Tuner class and genetic evolution algorithms.
  • Knowledge Distillation: Learn how to improve model performance by transferring knowledge from a larger teacher model to a smaller student model using feature-based distillation.
  • K-Fold Cross Validation: Learn how to improve model generalization using the K-Fold cross-validation technique.
  • Customizing Trainer: Learn how to subclass the YOLO trainer to log custom metrics, add class-weighted loss, customize model saving, freeze/unfreeze the backbone, and set per-layer learning rates.
  • Model YAML Configuration Guide: A deep dive into Ultralytics model architecture definitions. Explore the YAML format, understand the module resolution system, and learn how to integrate custom modules.

Evaluate & troubleshoot#

  • YOLO Performance Metrics ⭐ ESSENTIAL: Understand the key metrics like mAP, IoU, and F1 score used to evaluate the performance of your YOLO models. Includes practical examples and tips on how to improve detection accuracy and speed.
  • Insights on Model Evaluation and Fine-Tuning: Evaluate computer vision models with metrics like mAP and IoU, then act on what the metrics expose to improve detection accuracy.
  • Model Testing: Learn how to test computer vision models on unseen data, validate YOLO26 models, and catch overfitting, underfitting, and data leakage before deployment.
  • YOLO Common Issues ⭐ RECOMMENDED: Practical solutions and troubleshooting tips to the most frequently encountered issues when working with Ultralytics YOLO models.
  • Maintaining Your Computer Vision Model: Understand the key practices for monitoring, maintaining, and documenting computer vision models to maintain accuracy, spot anomalies, and mitigate data drift.

Deploy & serve#

  • Model Deployment Options: Overview of YOLO model deployment formats like ONNX, OpenVINO, and TensorRT, with pros and cons for each to inform your deployment strategy.
  • Best Practices for Model Deployment: Walk through tips and best practices for efficiently deploying models in computer vision projects, with a focus on optimization, troubleshooting, and security.
  • Export Non-YOLO Models: Use Ultralytics standalone export utilities to convert any torch.nn.Module (timm, torchvision, custom) to TorchScript, ONNX, OpenVINO, CoreML, Core AI, TensorFlow SavedModel, PaddlePaddle, MNN, NCNN, and ExecuTorch.
  • End-to-End Detection: Choose NMS or NMS-free inference and understand output formats and export compatibility.
  • Triton Inference Server Integration: Integrate Ultralytics YOLO26 with NVIDIA Triton Inference Server for scalable, efficient deep learning inference deployments.
  • YOLO Thread-Safe Inference: Guidelines for performing inference with YOLO models in a thread-safe manner. Learn the importance of thread safety and best practices to prevent race conditions and ensure consistent predictions.
  • ROS Quickstart: Learn how to integrate YOLO with the Robot Operating System (ROS) for real-time object detection in robotics applications, including point cloud and depth images.
  • Vertex AI Deployment with Docker: Streamlined guide to containerizing YOLO models with Docker and deploying them on Google Cloud Vertex AI—covering build, push, autoscaling, and monitoring.

Optimize inference#

Edge & embedded hardware#

Contribute to Our Guides#

We welcome contributions from the community! If you've mastered a particular aspect of Ultralytics YOLO that's not yet covered in our guides, we encourage you to share your expertise. Writing a guide is a great way to give back to the community and help us make our documentation more comprehensive and user-friendly.

To get started, please read our Contributing Guide for guidelines on how to open a Pull Request (PR). When adding a new guide, place it under the category above that matches its project stage and keep it to a single page type — a step-by-step tutorial, a task-focused how-to, or a reference — so the collection stays easy to browse as it grows. We look forward to your contributions.

FAQ#

  • Training a custom object detection model with Ultralytics YOLO is straightforward. Start by preparing your dataset in the correct format and installing the Ultralytics package. Use the following code to initiate training:

    Example
    from ultralytics import YOLO
    
    model = YOLO("yolo26n.pt")  # Load a pretrained YOLO model
    model.train(data="path/to/dataset.yaml", epochs=50)  # Train on custom dataset
  • Evaluating your YOLO model performance is crucial to understanding its efficacy. Key metrics include Mean Average Precision (mAP), Intersection over Union (IoU), and F1 score. These metrics help assess the accuracy and precision of object detection tasks. You can learn more about these metrics and how to improve your model in our YOLO Performance Metrics guide.

  • Ultralytics Platform is an end-to-end, no-code workspace for dataset annotation, experiment tracking, cloud training, export, and dedicated inference endpoints for YOLO models, suited to both beginners and professionals.

  • Common issues during YOLO model training include data formatting errors, model architecture mismatches, and insufficient training data. To address these, ensure your dataset is correctly formatted, check for compatible model versions, and augment your training data. For a comprehensive list of solutions, refer to our YOLO Common Issues guide.

  • Deploying YOLO models on edge devices like NVIDIA Jetson and Raspberry Pi requires converting the model to a compatible format such as TensorRT or LiteRT. Follow our step-by-step guides for NVIDIA Jetson and Raspberry Pi deployments to get started with real-time object detection on edge hardware. These guides cover installation, configuration, and performance optimization.

Comments30

Ask a question, share your results, or help someone else.

  1. safdarhamid64-cpusafdarhamid64-cpuGitHub

    i have done everything using your docker method everything , using AI chatbots , but still i am unable to run the yolo , plzz provide me a solution that will work for every Raspberry Pi4 because its really so much frustrating

  2. tutorialsyolotutorialsyoloGitHub

    Hi, I am trying to improve the convolutional layers in the nn module like in conv.py or block.py as novelty for my research. The location is like "ultralytics/ultralytics/nn/modules/conv.py. Could you please tell me where else i should update/call the new block which I improved? Because it gives me error when I am adding those blocks in the cfg/.yaml files for training in a custom dataset. Thank you

  3. IshfazIshfazGitHub

    Hello,

    I'm using YOLOv8 for object detection, and I have only three classes in my dataset. However, when I generate the confusion matrix after training or validation, I notice that it shows a 4x4 matrix instead of the expected 3x3.

    It seems like an extra class, possibly a "background" or "null" class, is being added automatically.

    How can I remove this extra background class so that my confusion matrix only reflects the three actual classes I have trained on?

  4. AashishThakur1321AashishThakur1321GitHub

    can you tell the path, where downloaded model weights are stored as i manually want to add the weights to the folder as i don't have internet access on server

    1. Glenn JocherGlenn JocherUltralytics

      @AashishThakur1321 the default location where Ultralytics models are stored depends on your operating system, but it's typically within a directory in your user's home folder; you can find more specific details by checking the "Settings" section when you run from ultralytics import settings; print(settings).

      1
  5. ghostghostGitHub

    Hello, I am working on a project to detect different types of cells. I already have a trained model, thanks to Ultralytics! I want to increase my dataset and tried using the auto-annotate function. The function works well but annotates objects in polygons. I need annotation in rectangular bounding boxes. Can you please help with this problem? https://docs.ultralytics.com/reference/data/annotator/

    1. Glenn JocherGlenn JocherUltralytics

      @kartmyco thank you for your message! While the auto-annotate function currently outputs polygon annotations, you can convert them to rectangular bounding boxes using tools like cvat or labelme, or you can write a custom script to approximate polygons into rectangular boxes. For details on data annotation tools, you can refer to our guide on data collection and annotation. Let us know if you have additional questions!

    2. ghostghostGitHub

      Hello Glenn, Thank you so much for your reply. I will try to approximate the polygons in rectangular bounding boxes.

  6. jdonzajdonzaGitHub

    I decided to make a different thread here as it is related to a different topic. But I wanted to know if you guys had documentation that went into the specifics of how the YOLO models are created. I am interested to learn more about CNN's, how they work, and how it relates to the image processing of YOLO.

    1. Glenn JocherGlenn JocherUltralytics

      @jdonza for detailed information on how YOLO models are created and how CNNs work in relation to YOLO, please refer to our comprehensive guides at https://docs.ultralytics.com/guides/. These resources cover various aspects of YOLO, including its architecture and image processing techniques.

  7. jdonzajdonzaGitHub

    Hello,

    Are there any tutorials showing how to train a YOLOv8 model using multiple devices for faster training? I read the instructions for YOLOv5 but got a bit lost. Step by step instructions would be greatly appreciated!

    Thank you!

    1. Glenn JocherGlenn JocherUltralytics

      @jdonza hello,

      For training YOLOv8 using multiple devices, please refer to our Multi-GPU Training guide. It provides step-by-step instructions to help you set up and run training across multiple GPUs.

      Thank you!

    2. jdonzajdonzaGitHub

      Thank you for the response! What I am still confused with is the following line of code.

      results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device=[0, 1])

      Here are a few questions I had.

      1. I have one GPU on my computer currently. If I had another device that also had the same GPU, how does YOLO know which computer is 0 and which is 1? Is there a physical connection of some sort that needs to occur?
      2. If you had a computer with multiple GPU's, the same questions arises. How does YOLO know which is 0 and which is 1?

      Overall, I am confused with the set-up steps that need to occur before simply inputting "device=[0,1]".

      Sorry if my questions appear trivial. I am a beginner and do not have much experience with network configurations like this!

      Thanks!

    3. Glenn JocherGlenn JocherUltralytics

      @jdonza to address your questions:

      1. YOLOv8 does not support multi-device training across different computers. Each device ID (e.g., 0, 1) refers to GPUs within the same machine.
      2. For a computer with multiple GPUs, device IDs are assigned based on the order in which GPUs are detected by the system. You can verify GPU IDs using nvidia-smi.

      For more details, please refer to the Multi-GPU Training guide.

    4. jdonzajdonzaGitHub

      Was this capability eliminated? The link you provided has a drop-down section labeled "Use Multiple Machines" which appears to provide some sort of framework to accomplish this.

    5. Glenn JocherGlenn JocherUltralytics

      @jdonza the capability for multi-machine training is not supported in YOLOv8. The "Use Multiple Machines" section in the documentation you referenced may pertain to older versions or different contexts. For multi-GPU training on a single machine, you can use the device=[0,1] argument. If you have further questions, please refer to the Multi-GPU Training guide.

    6. Glenn JocherGlenn JocherUltralytics

      @jdonza you're welcome! For training YOLOv8 on multiple GPUs within a single machine, you can use the device=[0,1] argument. Each GPU is identified by its ID, which you can check using nvidia-smi. Multi-machine training is not supported. For more details, please refer to the Multi-GPU Training guide.

    7. Ephraim-BryskiEphraim-BryskiGitHub

      While not supported in YOLOv8, I did see reference to training across multiple computers in the YOLOv5 documentation:

      (I believe this is what jdonza was referring to before). Does this allow for training across multiple computers for YOLOv5, but is no longer supported in YOLOv8? If so, would using YOLOv5 instead of v8 be recommended for this use case? Thanks!

    8. Glenn JocherGlenn JocherUltralytics

      Training across multiple computers is supported in YOLOv5 using DistributedDataParallel, but this feature is not available in YOLOv8. If multi-machine training is essential for your use case, using YOLOv5 would be recommended. For more details, please refer to the YOLOv5 documentation.

  8. TanWeeKangTanWeeKangGitHub

    hi, i am doing a project about food detection. the detection results were great. however, there are some overlapping bboxes for some categories of food. some input images will have this category and some will have others. how can i apply nms to retrieve only the highest conf score of the detection and remove overlapping bboxes? i run inference on my best.pt model by giving it input images

    1. Glenn JocherGlenn JocherUltralytics(edited)

      Hi there! It's great to hear that your food detection project is yielding excellent results! 🎉

      To address the issue of overlapping bounding boxes, you can apply Non-Maximum Suppression (NMS) to retain only the highest confidence score detections and remove the overlapping ones. YOLO models typically handle NMS internally, but you can customize the NMS settings during inference to better suit your needs.

      Here's how you can do it:

      Using Python

      If you're running inference in a Python environment, you can set the conf (confidence threshold) and iou (IoU threshold for NMS) parameters when calling the predict method. Here's an example:

      from ultralytics import YOLO
      
      # Load your custom-trained model
      model = YOLO('path/to/best.pt')
      
      # Run inference with custom NMS settings
      results = model.predict(source='path/to/your/image.jpg', conf=0.25, iou=0.45)
      
      # Display results
      results[0].show()

      Using CLI

      If you're using the command line interface, you can specify these parameters directly in your command:

      yolo predict model=path/to/best.pt source='path/to/your/image.jpg' conf=0.25 iou=0.45

      Explanation

      • conf: This sets the minimum confidence threshold for detections. Detections with a confidence score below this value will be discarded.
      • iou: This sets the IoU threshold for NMS. Detections with an IoU greater than this value will be considered overlapping, and only the one with the highest confidence score will be kept.

      For more detailed information on inference and NMS settings, you can refer to the YOLO Predict Documentation.

      If you encounter any issues or need further assistance, please ensure you're using the latest versions of torch and ultralytics. If the problem persists, providing a minimum reproducible example would be very helpful. You can find guidelines on creating one here: Minimum Reproducible Example.

      Happy coding, and best of luck with your project! 🚀

    2. TanWeeKangTanWeeKangGitHub

      because the goal for now is to remove overlapping, if i set the iou threshold on the high side, the image doesnt differ much from the original detected image, where there are many overlappings. if i set to a low iou threshold, more overlappings will be removed.

    3. TanWeeKangTanWeeKangGitHub

      another thing is that for my food detection i have 5 classes/categories of food. under these 5 categories i have variety of food for each category, but i label and train the model on these 5 classes, for simplicity sake i did not go into detail about what kind of food is that, lets say meat we have fish, pork etc. the model see either of those and classify as meat. although they are from same classes, they might have different prices. now how can i use segmentation( maybe from opencv) to distinguish the image i used to run inference on my best.pt model to identify the difference in meat like fish, pork to have different prices?

    4. Glenn JocherGlenn JocherUltralytics(edited)

      Hi there! Thanks for reaching out and providing detailed feedback on your experience with overlapping bounding boxes in your food detection project. It's fantastic to hear that your detection results are generally great! 🎉

      To address the issue of overlapping bounding boxes, adjusting the IoU threshold is indeed a key factor. Here’s a more refined approach to help you achieve the best balance:

      Fine-Tuning IoU Threshold

      • High IoU Threshold: Retains more overlapping boxes, which might be useful if you want to ensure that no potential detections are missed.
      • Low IoU Threshold: Removes more overlapping boxes, which can help in reducing redundancy but might risk missing some detections.

      Practical Steps

      1. Experiment with Intermediate Values: Instead of setting the IoU threshold to extremes, try intermediate values (e.g., 0.3, 0.4, 0.5) to find a sweet spot that minimizes overlaps without losing important detections.
      2. Confidence Threshold: Adjust the confidence threshold (conf) to filter out low-confidence detections, which can also help in reducing overlaps.

      Example Code

      Here’s how you can apply these settings in Python:

      from ultralytics import YOLO
      
      # Load your custom-trained model
      model = YOLO('path/to/best.pt')
      
      # Run inference with custom NMS settings
      results = model.predict(source='path/to/your/image.jpg', conf=0.25, iou=0.45)
      
      # Display results
      results[0].show()

      And using the CLI:

      yolo predict model=path/to/best.pt source='path/to/your/image.jpg' conf=0.25 iou=0.45

      Additional Resources

      For more detailed guidance on optimizing your model and handling common issues, you might find the following guides helpful:

      If you continue to experience issues, please ensure you are using the latest versions of torch and ultralytics. If the problem persists, providing a minimum reproducible example would be very helpful. You can find guidelines on creating one here: Minimum Reproducible Example.

      Feel free to reach out if you have any more questions or need further assistance. Happy coding! 🚀

    5. TanWeeKangTanWeeKangGitHub

      another thing is that for my food detection i have 5 classes/categories of food. under these 5 categories i have variety of food for each category, but i label and train the model on these 5 classes, for simplicity sake i did not go into detail about what kind of food is that, lets say meat we have fish, pork etc. the model see either of those and classify as meat. although they are from same classes, they might have different prices. now how can i use segmentation( maybe from opencv) to distinguish the image i used to run inference on my best.pt model to identify the difference in meat like fish, pork to have different prices?

    6. Glenn JocherGlenn JocherUltralytics

      Hi there! It's fantastic to hear about your progress with food detection using YOLO. 😊

      To distinguish between different types of food within the same category (like fish and pork under "meat"), you can leverage segmentation techniques. Here's a step-by-step approach to achieve this:

      1. Segmentation with OpenCV

      You can use OpenCV to perform image segmentation, which will help you isolate different types of food within the same category. Here's a basic example of how you might use OpenCV for segmentation:

      import cv2
      import numpy as np
      
      # Load the image
      image = cv2.imread('path/to/your/image.jpg')
      
      # Convert to grayscale
      gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
      
      # Apply GaussianBlur to reduce noise and improve contour detection
      blurred = cv2.GaussianBlur(gray, (5, 5), 0)
      
      # Use Canny edge detection
      edges = cv2.Canny(blurred, 50, 150)
      
      # Find contours
      contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
      
      # Draw contours on the original image
      cv2.drawContours(image, contours, -1, (0, 255, 0), 2)
      
      # Display the result
      cv2.imshow('Segmented Image', image)
      cv2.waitKey(0)
      cv2.destroyAllWindows()

      2. Combining YOLO Detection with Segmentation

      You can combine the bounding boxes from your YOLO model with segmentation to further classify the detected objects. Here’s a conceptual approach:

      1. Run YOLO Inference: Use your trained YOLO model to detect the general categories (e.g., meat).
      2. Apply Segmentation: Within each detected bounding box, apply segmentation to isolate different types of food.
      3. Classify Segmented Regions: Use additional classification models or heuristics to distinguish between types like fish and pork.

      3. Advanced Segmentation Techniques

      For more precise segmentation, consider using advanced models like Mask R-CNN or leveraging pre-trained segmentation models available in frameworks like PyTorch or TensorFlow.

      Example with YOLO and Segmentation

      Here’s a more integrated example combining YOLO detection with OpenCV segmentation:

      from ultralytics import YOLO
      import cv2
      
      # Load your custom-trained YOLO model
      model = YOLO('path/to/best.pt')
      
      # Run inference
      results = model.predict(source='path/to/your/image.jpg', conf=0.25, iou=0.45)
      
      # Process each detected bounding box
      for result in results:
          for box in result.boxes:
              x1, y1, x2, y2 = map(int, box.xyxy[0])
              cropped_img = result.orig_img[y1:y2, x1:x2]
      
              # Convert to grayscale and apply segmentation
              gray = cv2.cvtColor(cropped_img, cv2.COLOR_BGR2GRAY)
              blurred = cv2.GaussianBlur(gray, (5, 5), 0)
              edges = cv2.Canny(blurred, 50, 150)
              contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
              cv2.drawContours(cropped_img, contours, -1, (0, 255, 0), 2)
      
              # Display the segmented image
              cv2.imshow('Segmented Image', cropped_img)
              cv2.waitKey(0)
      
      cv2.destroyAllWindows()

      Further Reading

      For more detailed guides and advanced techniques, you might find these resources helpful:

      Feel free to experiment with these techniques and adjust the parameters to better suit your specific use case. If you have any more questions or need further assistance, don't hesitate to ask. Happy coding! 🚀

  9. thisisqiuqiuqiuthisisqiuqiuqiuGitHub

    Thank you very much for your letter. Your reply is very helpful to my experimental training. I understand how to set up the basic model training. I wish you all success in your future work. 

    ------------------ 原始邮件 ------------------ 发件人: "ultralytics/ultralytics" @.>; 发送时间: 2024年5月20日(星期一) 中午12:11 @.>; @.@.>; 主题: Re: [ultralytics/ultralytics] zh/guides/ (Discussion #12787)

    Hello! The number of epochs needed for training the YOLOv8 base model can vary depending on your specific dataset and the complexity of the task. While 500 epochs might be necessary for some scenarios to achieve optimal results, it's not a strict requirement for all cases.

    A good practice is to monitor the training process for signs of convergence, such as stable validation loss and accuracy metrics. You can start with fewer epochs, like 100 or 200, and evaluate the model's performance. If the results are not satisfactory, you can continue training for more epochs or consider adjusting other hyperparameters.

    Here's a simple example to start training with a specified number of epochs: yolo train data=coco128.yaml model=yolov8n.pt epochs=100

    Adjust the epochs value as needed based on your observations. Happy training! 😊

    — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: @.***>

    1. Glenn JocherGlenn JocherUltralytics(edited)

      Hello! The number of epochs needed for training the YOLO base model can vary depending on your specific dataset and the complexity of the task. While 500 epochs might be necessary for some scenarios to achieve optimal results, it's not a strict requirement for all cases.

      A good practice is to monitor the training process for signs of convergence, such as stable validation loss and accuracy metrics. You can start with fewer epochs, like 100 or 200, and evaluate the model's performance. If the results are not satisfactory, you can continue training for more epochs or consider adjusting other hyperparameters.

      Here's a simple example to start training with a specified number of epochs:

      yolo train data=coco128.yaml model=yolo26n.pt epochs=100

      Adjust the epochs value as needed based on your observations. Happy training! 😊