ultralytics/docs/usage/python.md

The simplest way of simply using YOLOv8 directly in a Python environment.

!!! example "Train"

=== "From pretrained(recommended)"
    ```python
    from ultralytics import YOLO

    model = YOLO('yolov8n.pt') # pass any model type
    model.train(epochs=5)
    ```

=== "From scratch"
    ```python
    from ultralytics import YOLO

    model = YOLO('yolov8n.yaml')
    model.train(data='coco128.yaml', epochs=5)
    ```

=== "Resume"
    ```python
    # TODO: Resume feature is under development and should be released soon.
    model = YOLO("last.pt")
    model.train(resume=True)
    ```

!!! example "Val"

=== "Val after training"
    ```python
      from ultralytics import YOLO

      model = YOLO('yolov8n.yaml')
      model.train(data='coco128.yaml', epochs=5)
      model.val()  # It'll automatically evaluate the data you trained.
    ```

=== "Val independently"
    ```python
      from ultralytics import YOLO

      model = YOLO("model.pt")
      # It'll use the data yaml file in model.pt if you don't set data.
      model.val()
      # or you can set the data you want to val
      model.val(data='coco128.yaml')
    ```

!!! example "Predict"

=== "From source"
    ```python
    from ultralytics import YOLO
    from PIL import Image
    import cv2

    model = YOLO("model.pt")
    # accepts all formats - image/dir/Path/URL/video/PIL/ndarray. 0 for webcam
    results = model.predict(source="0")
    results = model.predict(source="folder", show=True) # Display preds. Accepts all YOLO predict arguments

    # from PIL
    im1 = Image.open("bus.jpg")
    results = model.predict(source=im1, save=True)  # save plotted images

    # from ndarray
    im2 = cv2.imread("bus.jpg")
    results = model.predict(source=im2, save=True, save_txt=True)  # save predictions as labels

    # from list of PIL/ndarray
    results = model.predict(source=[im1, im2])
    ```

=== "Results usage"
    ```python
    # results would be a list of Results object including all the predictions by default
    # but be careful as it could occupy a lot memory when there're many images, 
    # especially the task is segmentation.
    # 1. return as a list
    results = model.predict(source="folder")

    # results would be a generator which is more friendly to memory by setting stream=True
    # 2. return as a generator
    results = model.predict(source=0, stream=True)

    for result in results:
        # detection
        result.boxes.xyxy   # box with xyxy format, (N, 4)
        result.boxes.xywh   # box with xywh format, (N, 4)
        result.boxes.xyxyn  # box with xyxy format but normalized, (N, 4)
        result.boxes.xywhn  # box with xywh format but normalized, (N, 4)
        result.boxes.conf   # confidence score, (N, 1)
        result.boxes.cls    # cls, (N, 1)

        # segmentation
        result.masks.masks     # masks, (N, H, W)
        result.masks.segments  # bounding coordinates of masks, List[segment] * N

        # classification
        result.probs     # cls prob, (num_class, )

    # Each result is composed of torch.Tensor by default, 
    # in which you can easily use following functionality:
    result = result.cuda()
    result = result.cpu()
    result = result.to("cpu")
    result = result.numpy()
    ```

!!! note "Export and Deployment"

=== "Export, Fuse & info" 
    ```python
    from ultralytics import YOLO

    model = YOLO("model.pt")
    model.fuse()  
    model.info(verbose=True)  # Print model information
    model.export(format=)  # TODO: 

    ```
=== "Deployment"


More functionality coming soon

To know more about using YOLO models, refer Model class Reference

Model reference{ .md-button .md-button--primary}

---

Using Trainers

YOLO model class is a high-level wrapper on the Trainer classes. Each YOLO task has its own trainer that inherits from BaseTrainer.

!!! tip "Detection Trainer Example"

    ```python
    from ultralytics.yolo import v8 import DetectionTrainer, DetectionValidator, DetectionPredictor

    # trainer
    trainer = DetectionTrainer(overrides={})
    trainer.train()
    trained_model = trainer.best

    # Validator
    val = DetectionValidator(args=...)
    val(model=trained_model)

    # predictor
    pred = DetectionPredictor(overrides={})
    pred(source=SOURCE, model=trained_model)

    # resume from last weight
    overrides["resume"] = trainer.last
    trainer = detect.DetectionTrainer(overrides=overrides)
    ```

You can easily customize Trainers to support custom tasks or explore R&D ideas. Learn more about Customizing Trainers, Validators and Predictors to suit your project needs in the Customization Section.

Customization tutorials{ .md-button .md-button--primary}