Ultralytics YOLO27: Join the waitlist.
Get Started

Model Prediction with Ultralytics YOLO

Ultralytics YOLO ecosystem and integrations

Introduction#

In machine learning and computer vision, making sense of visual data with a trained model is called inference or prediction. Ultralytics YOLO26 predict mode runs fast, real-time inference across a wide range of data sources.

See the unreleased YOLO27 preview for planned inference examples.



Watch: How to Extract Results from Ultralytics YOLO26 Tasks for Custom Projects 🚀

Real-world Applications#

ManufacturingSportsSafety
Vehicle Spare Parts DetectionFootball Player DetectionPeople Fall Detection

Why Use Ultralytics YOLO for Inference?#

Key reasons to use YOLO26's predict mode:

  • Versatility: Run inference on images, videos, and live streams.
  • Performance: Engineered for real-time, high-speed processing without sacrificing accuracy.
  • Ease of Use: Intuitive Python and CLI interfaces for rapid deployment and testing.
  • Highly Customizable: Various settings and parameters to tune the model's inference behavior according to your specific requirements.
  • Production Ready: Deploy models as Ultralytics Platform inference endpoints with auto-scaling and monitoring, or run inference locally.

Key Features of Predict Mode#

YOLO26's predict mode includes:

  • Multiple Data Source Compatibility: Predict mode accepts individual images, collections of images, video files, and real-time video streams.
  • Streaming Mode: Use the streaming feature to generate a memory-efficient generator of Results objects. Enable this by setting stream=True in the predictor's call method. Unlike the default behavior (stream=False), which returns a list containing all results, stream=True yields results one at a time, making it especially useful for long videos and live streams.
  • Batch Processing: Process multiple images or video frames in a single batch, further reducing total inference time.
  • Integration Friendly: Integrate with existing data pipelines and other software components through a flexible API.

Ultralytics YOLO models return either a Python list of Results objects or a memory-efficient generator of Results objects when stream=True is passed to the model during inference:

Predict
from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")  # pretrained YOLO26n model

# Run batched inference on a list of images
results = model(["image1.jpg", "image2.jpg"])  # return a list of Results objects

# Process results list
for result in results:
    boxes = result.boxes  # Boxes object for bounding box outputs
    masks = result.masks  # Masks object for segmentation masks outputs
    keypoints = result.keypoints  # Keypoints object for pose outputs
    probs = result.probs  # Probs object for classification outputs
    obb = result.obb  # Oriented boxes object for OBB outputs
    result.show()  # display to screen
    result.save(filename="result.jpg")  # save to disk

Inference Sources#

YOLO26 can process different types of input sources for inference, as shown in the table below. The sources include static images, video streams, and various data formats. The table also indicates whether each source can be used in streaming mode with the argument stream=True ✅. Streaming mode is beneficial for processing videos or live streams as it creates a generator of results instead of loading all frames into memory.

Tip

Use stream=True for processing long videos or large datasets to efficiently manage memory. When stream=False, the results for all frames or data points are stored in memory, which can quickly add up and cause out-of-memory errors for large inputs. In contrast, stream=True utilizes a generator, which only keeps the results of the current frame or data point in memory, significantly reducing memory consumption and preventing out-of-memory issues.

SourceExampleTypeNotes
image'image.jpg'str or PathSingle image file.
URL'https://ultralytics.com/images/bus.jpg'strURL to an image.
screenshot ✅'screen'strCapture the screen continuously until stopped.
PILImage.open('image.jpg')PIL.ImageHWC format with RGB channels.
OpenCVcv2.imread('image.jpg')np.ndarrayHWC format with BGR channels uint8 (0-255).
NumPynp.zeros((640,1280,3))np.ndarrayHWC format with BGR channels uint8 (0-255).
torchtorch.zeros(16,3,320,640)torch.TensorBCHW format with RGB channels float32 (0.0-1.0).
CSV'sources.csv'str or PathCSV file containing paths to images, videos, or directories.
video ✅'video.mp4'str or PathVideo file in formats like MP4, AVI, etc.
directory ✅'path/'str or PathPath to a directory containing images or videos.
glob ✅'path/*.jpg'strGlob pattern to match multiple files. Use the * character as a wildcard.
YouTube ✅'https://youtu.be/LNwODJXcvt4'strURL to a YouTube video.
stream ✅'rtsp://example.com/media.mp4'strURL for streaming protocols such as RTSP, RTMP, TCP, or an IP address.
multi-stream ✅'list.streams'str or Path*.streams text file with one stream URL per row, i.e., 8 streams will run at batch-size 8.
webcam ✅0intIndex of the connected camera device to run inference on.

Below are code examples for using each source type:

Prediction sources

Run inference on an image file.

from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Define path to the image file
source = "path/to/image.jpg"

# Run inference on the source
results = model(source)  # list of Results objects

Inference Arguments#

model.predict() accepts multiple arguments that can be passed at inference time to override defaults:

Fixed shape vs minimum rectangle (rect)#

By default, predict uses rect=True, which enables minimum-rectangle padding when possible. The image is scaled to fit inside imgsz and padded only to the nearest stride multiple, so the final tensor may be smaller than imgsz. Minimum-rectangle padding is only used when all images in the batch have the same shape and the backend supports it (PyTorch .pt, or a dynamic-shape export such as dynamic ONNX). Otherwise, images are padded to the full imgsz target. Depth and RT-DETR models ignore rect and stretch every image to the full imgsz without padding.

Use rect=False to always use the full imgsz target. This is recommended when you need a fixed input size to match exported models (ONNX, TensorRT, etc.).

Integer vs tuple imgsz

  • An integer imgsz=640 becomes a square target (640, 640) after stride rounding.
  • A tuple imgsz=(384, 672) sets a rectangular target. With rect=True, the actual tensor can be smaller than this target.

Training vs predict/export

Training accepts only a single integer imgsz (a [h, w] list is coerced to the largest value). Predict and export accept either an integer or a (height, width) tuple.

Example
from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on 'bus.jpg' with arguments
model.predict("https://ultralytics.com/images/bus.jpg", save=True, imgsz=320, conf=0.25)

Inference arguments:

ArgumentTypeDefaultDescription
sourcestr or int or NoneNoneSpecifies the data source for inference. Can be an image path, video file, directory, URL, or device ID for live feeds. If omitted, a warning is logged and the model falls back to the built-in demo assets (ultralytics/assets, or a demo URL for OBB). Supports a wide range of formats and sources, enabling flexible application across different types of input.
conffloat0.25Sets the minimum confidence threshold for detections. Objects detected with confidence below this threshold will be disregarded. Adjusting this value can help reduce false positives.
ioufloat0.5Intersection Over Union (IoU) threshold for Non-Maximum Suppression (NMS). Lower values result in fewer detections by eliminating overlapping boxes, useful for reducing duplicates.
imgszint or tuple640Letterbox target. An integer gives a square N×N; a tuple gives (height, width). With rect=True, the actual tensor may be smaller than this target due to minimum-rectangle padding. Use rect=False for a fixed size. See Fixed shape vs minimum rectangle.
rectboolTrueIf True, use minimum-rectangle padding when possible (same-shape batch and supported backend). If False, always use the full imgsz. See Fixed shape vs minimum rectangle. Ignored for depth and RT-DETR models, which stretch images to the full imgsz without padding.
quantizeint or strNoneInference precision: 16/"fp16" and 32/"fp32"/unset select FP16 or FP32 compute for PyTorch and TorchScript models (FP32 on CPU); other formats use the precision their artifact and runtime select. At 16 OpenVINO still FP16-rounds the input on the client and widens it back to FP32, without changing the runtime precision. INT8/PTQ quantization is configured during export, then used by loading the exported model. Replaces the deprecated half flag.
devicestrNoneSpecifies the device for inference (e.g., cpu, cuda:0, 0, npu or npu:0). Allows users to select between CPU, a specific GPU, Huawei Ascend NPU, or other compute devices for model execution. OpenVINO and LiteRT models run xpu and npu on the Intel GPU and NPU; see inference devices for every format.
dnnboolFalseIf True, uses the OpenCV DNN module instead of ONNX Runtime for ONNX model inference.
datastrNonePath to a dataset YAML (e.g. coco8.yaml) read only for its names, and only when the loaded model carries no class names of its own: a third-party export, or an Ultralytics export separated from the metadata it ships with. Such a model otherwise reports class0, class1, and so on.
batchint1Specifies the batch size for inference (only works when the source is a directory, video file, or .txt file). A larger batch size can provide higher throughput, shortening the total amount of time required for inference.
tilebool or intFalseRuns fixed tiled inference and returns outputs in original-image coordinates. True uses imgsz; a positive int sets tile size. See High Resolution Tiling.
max_detint300Maximum number of detections allowed per image. Limits the total number of objects the model can detect in a single inference, preventing excessive outputs in dense scenes.
vid_strideint1Frame stride for video inputs. Allows skipping frames in videos to speed up processing at the cost of temporal resolution. A value of 1 processes every frame, higher values skip frames.
stream_bufferboolFalseDetermines whether to queue incoming frames for video streams. If False, old frames get dropped to accommodate new frames (optimized for real-time applications). If True, queues new frames in a buffer, ensuring no frames get skipped, but will cause latency if inference FPS is lower than stream FPS.
visualizeboolFalseSaves a class activation heatmap next to each prediction, showing which pixels raised the predicted class scores. Respects conf and classes, so classes=[0] maps only that class. Only available for Ultralytics PyTorch models.
augmentboolFalseEnables test-time augmentation (TTA) for predictions, potentially improving detection robustness at the cost of inference speed. Only available for Ultralytics PyTorch models.
agnostic_nmsboolFalseEnables class-agnostic Non-Maximum Suppression (NMS), suppressing lower-scoring overlapping boxes across different classes rather than only within the same class. Useful in multi-class detection scenarios where class overlap is common. With NMS-free inference (nms=False on YOLO26 or YOLOv10), this only prevents the same detection from appearing with multiple class labels (IoU=1.0 duplicates) and does not perform IoU-threshold-based suppression between distinct boxes.
classeslist[int]NoneFilters predictions to a set of class IDs. Only detections belonging to the specified classes will be returned. Useful for focusing on relevant objects in multi-class detection tasks.
retina_masksboolFalseReturns high-resolution segmentation masks. The returned masks (masks.data) will match the original image size if enabled. If disabled, they have the image size used during inference.
embedlist[int]NoneSpecifies the layers from which to extract feature vectors or embeddings. Use model.embed(source) for second-to-last layer embeddings, or model.predict(source, embed=[layer]) to select specific layers. Useful for downstream tasks like clustering or similarity search. Only available for Ultralytics PyTorch models.
projectstrNoneName of the project directory where prediction outputs are saved if save is enabled. A relative path is placed under runs_dir/<task>, while an absolute path is used as-is.
namestrNoneName of the prediction run. Used for creating a subdirectory within the project folder, where prediction outputs are stored if save is enabled.
streamboolFalseEnables memory-efficient processing for long videos or numerous images by returning a generator of Results objects instead of loading all frames into memory at once.
verboseboolTrueControls whether to display detailed inference logs in the terminal, providing real-time feedback on the prediction process.
compilebool or strFalseEnables PyTorch 2.x torch.compile graph compilation with backend='inductor'. Accepts True → "default", False → disables, or a string mode such as "default", "reduce-overhead", "max-autotune-no-cudagraphs". Falls back to eager with a warning if unsupported.
channels_lastboolNoneUses the channels_last (NHWC) memory format for native PyTorch inference. None automatically enables it on oneDNN-enabled Linux and Windows x86 CPUs with PyTorch 1.13 or newer, False disables it, and True requests it on supported x86 CPU or CUDA devices. ARM64, MPS, older PyTorch versions, CPUs without oneDNN, and exported formats such as TensorRT and ONNX remain unchanged.
nmsbool, optionalNoneRuns one-to-many inference with NMS by default (None or True). Set False to use the NMS-free one-to-one head when available. See the End-to-End Detection guide for details.

Visualization arguments:

ArgumentTypeDefaultDescription
showboolFalseIf True, displays the annotated images or videos in a window. Useful for immediate visual feedback during development or testing.
saveboolFalse or TrueEnables saving of the annotated images or videos to files. Useful for documentation, further analysis, or sharing results. Defaults to True when using CLI & False when used in Python.
save_framesboolFalseWhen processing videos, saves individual frames as images. Useful for extracting specific frames or for detailed frame-by-frame analysis.
save_txtboolFalseSaves detection results in a text file, following the format [class] [x_center] [y_center] [width] [height] [confidence]. Useful for integration with other analysis tools.
save_confboolFalseIncludes confidence scores in the saved text files. Enhances the detail available for post-processing and analysis.
save_cropboolFalseSaves cropped images of detections. Useful for dataset augmentation, analysis, or creating focused datasets for specific objects.
show_labelsboolTrueDisplays labels for each detection in the visual output. Provides immediate understanding of detected objects.
show_confboolTrueDisplays the confidence score for each detection alongside the label. Gives insight into the model's certainty for each detection.
show_boxesboolTrueDraws bounding boxes around detected objects. Essential for visual identification and location of objects in images or video frames.
line_widthint or NoneNoneSpecifies the line width of bounding boxes. If None, the line width is automatically adjusted based on the image size. Provides visual customization for clarity.

Inference Devices#

device takes PyTorch device names for every model format, so the same value selects the same hardware whether you run a .pt checkpoint or an exported model. Leave it unset to use the best available device. Each runtime maps the name onto its own hardware, and validation and benchmarking take the same values:

Formatunsetcpu0 or cuda:0mpsxpunpu
PyTorch .pt, TorchScriptCUDA GPU, else CPUCPUNVIDIA GPUApple GPUIntel GPUHuawei Ascend NPU
ONNXCUDA GPU, else CPUCPUNVIDIA GPU (CUDA), AMD GPU (MIGraphX)Core ML--
TensorRTNVIDIA GPUNVIDIA GPUNVIDIA GPU---
OpenVINOOpenVINO AUTOIntel CPU--Intel GPU (xpu:1 is OpenVINO GPU.1)Intel NPU
LiteRTCPUCPU--Intel GPU through the OpenVINO pluginIntel NPU through the OpenVINO plugin
PaddlePaddleCUDA GPU, else CPUCPUNVIDIA GPU---

- means the runtime has no backend for that device. ONNX, TensorRT and PaddlePaddle check the name with PyTorch first, so they reject a device PyTorch cannot see and otherwise run on their default hardware. OpenVINO warns and falls back to AUTO when a requested Intel device is missing, and the LiteRT Intel plugin falls back to CPU. Other formats choose their own hardware: CoreML runs on the Apple Neural Engine and CPU, Edge TPU takes tpu:0, NCNN takes vulkan:0 for its Vulkan GPU path, and the remaining formats run on their target's CPU or accelerator. The older intel:cpu, intel:gpu and intel:npu names still work as deprecated aliases for cpu, xpu and npu.

Example
from ultralytics import YOLO

model = YOLO("yolo26n_openvino_model/")
results = model("https://ultralytics.com/images/bus.jpg", device="npu")  # Intel NPU

Image and Video Formats#

YOLO26 supports various image and video formats, as specified in ultralytics/data/utils.py. See the tables below for the valid suffixes and example predict commands.

Images#

The below table contains valid Ultralytics image formats.

Note

HEIC/HEIF formats require pi-heif, which is installed automatically on first use. AVIF is supported natively by Pillow.

Image SuffixesExample Predict CommandReference
.avifyolo predict source=image.avifAV1 Image File Format
.bmpyolo predict source=image.bmpMicrosoft BMP File Format
.dngyolo predict source=image.dngAdobe DNG
.heicyolo predict source=image.heicHigh Efficiency Image Format
.heifyolo predict source=image.heifHigh Efficiency Image Format
.jp2yolo predict source=image.jp2JPEG 2000
.jpegyolo predict source=image.jpegJPEG
.jpgyolo predict source=image.jpgJPEG
.mpoyolo predict source=image.mpoMulti Picture Object
.pngyolo predict source=image.pngPortable Network Graphics
.tifyolo predict source=image.tifTag Image File Format
.tiffyolo predict source=image.tiffTag Image File Format
.webpyolo predict source=image.webpWebP

Videos#

The below table contains valid Ultralytics video formats.

Video SuffixesExample Predict CommandReference
.asfyolo predict source=video.asfAdvanced Systems Format
.aviyolo predict source=video.aviAudio Video Interleave
.gifyolo predict source=video.gifGraphics Interchange Format
.m4vyolo predict source=video.m4vMPEG-4 Part 14
.mkvyolo predict source=video.mkvMatroska
.movyolo predict source=video.movQuickTime File Format
.mp4yolo predict source=video.mp4MPEG-4 Part 14 - Wikipedia
.mpegyolo predict source=video.mpegMPEG-1 Part 2
.mpgyolo predict source=video.mpgMPEG-1 Part 2
.tsyolo predict source=video.tsMPEG Transport Stream
.wmvyolo predict source=video.wmvWindows Media Video
.webmyolo predict source=video.webmWebM Project

Working with Results#

All Ultralytics predict() calls will return a list of Results objects:

Results
from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")
results = model(
    [
        "https://ultralytics.com/images/bus.jpg",
        "https://ultralytics.com/images/zidane.jpg",
    ]
)  # batch inference

Results objects have the following attributes:

AttributeTypeDescription
orig_imgnp.ndarrayThe original image as a NumPy array.
orig_shapetupleThe original image shape in (height, width) format.
boxesBoxes, optionalA Boxes object containing the detection bounding boxes.
masksMasks, optionalA Masks object containing the detection masks.
probsProbs, optionalA Probs object containing probabilities of each class for classification task.
keypointsKeypoints, optionalA Keypoints object containing detected keypoints for each object.
obbOBB, optionalAn OBB object containing oriented bounding boxes.
semantic_maskSemanticMask, optionalA SemanticMask object containing a dense per-pixel class map.
depthDepthMap, optionalA DepthMap object containing a dense per-pixel depth map.
speeddictA dictionary of preprocess, inference, and postprocess speeds in milliseconds per image.
namesdictA dictionary mapping class indices to class names.
pathstrThe path to the image file.
save_dirstr, optionalDirectory to save results.

Results by Task#

Which fields below populate depends on your model's task — compare detection, segmentation, semantic segmentation, depth estimation, classification, pose, and OBB if you haven't picked one yet. Each prediction returns one Results object per image or frame. The common fields above are always available, while the task-specific prediction data is stored in the fields below. YOLO coordinate and confidence tensors are torch.float32; probability tensors are torch.float32 unless the model runs in FP16 (quantize=16 with a PyTorch or TorchScript model off CPU, or an ONNX model with FP16 inputs), then torch.float16. After result.numpy(), tensors become NumPy arrays with matching NumPy dtypes. Instance masks are torch.uint8 binary tensors, while semantic masks use the smallest practical integer dtype for class IDs: torch.uint8, torch.int16, or torch.int32, depending on class count.

AttributeTypeShapeDescription
result.boxesBoxes(N)Detection boxes.
result.boxes.datatorch.float32(N,6/7)Raw [x1,y1,x2,y2,conf,cls], plus optional track ID.
result.boxes.xyxytorch.float32(N,4)xyxy pixel boxes.
result.boxes.conftorch.float32(N,)Confidence scores.
result.boxes.clstorch.float32(N,)Class IDs; cast to int for names.

Results objects have the following methods:

MethodReturn TypeDescription
update()NoneUpdates the Results object with new data such as boxes, masks, probs, obb, keypoints, semantic masks, or depth.
cpu()ResultsReturns a copy of the Results object with all tensors moved to CPU memory.
numpy()ResultsReturns a copy of the Results object with all tensors converted to NumPy arrays.
cuda()ResultsReturns a copy of the Results object with all tensors moved to GPU memory.
to()ResultsReturns a copy of the Results object with tensors moved to specified device and dtype.
new()ResultsCreates a new Results object with the same image, path, names, and speed attributes.
plot()np.ndarrayPlots detection results on an input BGR image and returns the annotated image.
show()NoneDisplays the image with annotated inference results.
save()strSaves annotated inference results image to file and returns the filename.
verbose()strReturns a log string for each task, detailing detection and classification outcomes.
save_txt()strSaves detection results to a text file and returns the path to the saved file.
save_crop()NoneSaves cropped detection images to specified directory.
summary()List[Dict[str, Any]]Converts inference results to a summarized dictionary with optional normalization.
to_df()DataFrameConverts detection results to a Polars DataFrame.
to_csv()strConverts detection results to CSV format.
to_json()strConverts detection results to JSON format.

For more details see the Results class documentation.

Boxes#

Boxes object can be used to index, manipulate, and convert bounding boxes to different formats.

Boxes
from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.boxes)  # print the Boxes object containing the detection bounding boxes

Here is a table for the Boxes class methods and properties, including their name, type, and description:

NameTypeDescription
cpu()MethodMove the object to CPU memory.
numpy()MethodConvert the object to a NumPy array.
cuda()MethodMove the object to CUDA memory.
to()MethodMove the object to the specified device.
xyxyProperty (torch.Tensor)Return the boxes in xyxy format.
confProperty (torch.Tensor)Return the confidence values of the boxes.
clsProperty (torch.Tensor)Return the class values of the boxes.
idProperty (torch.Tensor)Return the track IDs of the boxes (if available).
xywhProperty (torch.Tensor)Return the boxes in xywh format.
xyxynProperty (torch.Tensor)Return the boxes in xyxy format normalized by original image size.
xywhnProperty (torch.Tensor)Return the boxes in xywh format normalized by original image size.

For more details see the Boxes class documentation.

Masks#

Masks object can be used to index, manipulate and convert masks to segments.

Masks
from ultralytics import YOLO

# Load a pretrained YOLO26n-seg Segment model
model = YOLO("yolo26n-seg.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.masks)  # print the Masks object containing the detected instance masks

Here is a table for the Masks class methods and properties, including their name, type, and description:

NameTypeDescription
dataProperty (torch.Tensor)torch.uint8 binary mask tensor with shape (N,H,W) and values 0 or 1.
cpu()MethodReturns the masks tensor on CPU memory.
numpy()MethodReturns the masks tensor as a NumPy array.
cuda()MethodReturns the masks tensor on GPU memory.
to()MethodReturns the masks tensor with the specified device and dtype.
xynProperty (list[np.ndarray])A list of normalized mask polygons.
xyProperty (list[np.ndarray])A list of mask polygons in pixel coordinates.

For more details see the Masks class documentation.

SemanticMask#

SemanticMask stores one dense class map for semantic segmentation results. Unlike Masks, it does not contain one binary mask per object and does not provide polygon helpers.

SemanticMask
from ultralytics import YOLO

# Load a pretrained YOLO26n-sem Semantic model
model = YOLO("yolo26n-sem.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.semantic_mask.data)  # print the H x W class-ID map
NameTypeDescription
dataProperty (torch.Tensor)Class-ID map with shape (H,W). Dtype is torch.uint8, torch.int16, or torch.int32, selected by class count.
shapeProperty (tuple)Shape of the class map, usually matching result.orig_shape.
cpu()MethodReturns the semantic mask tensor on CPU memory.
numpy()MethodReturns the semantic mask tensor as a NumPy array.
cuda()MethodReturns the semantic mask tensor on GPU memory.
to()MethodReturns the semantic mask tensor with the specified device and dtype.

Keypoints#

Keypoints object can be used to index, manipulate and normalize coordinates.

Keypoints
from ultralytics import YOLO

# Load a pretrained YOLO26n-pose Pose model
model = YOLO("yolo26n-pose.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.keypoints)  # print the Keypoints object containing the detected keypoints

Here is a table for the Keypoints class methods and properties, including their name, type, and description:

NameTypeDescription
cpu()MethodReturns the keypoints tensor on CPU memory.
numpy()MethodReturns the keypoints tensor as a NumPy array.
cuda()MethodReturns the keypoints tensor on GPU memory.
to()MethodReturns the keypoints tensor with the specified device and dtype.
xynProperty (torch.Tensor)Normalized keypoint coordinates with shape (N,K,2).
xyProperty (torch.Tensor)Keypoint coordinates in pixels with shape (N,K,2).
confProperty (torch.Tensor)Returns confidence values of keypoints if available, else None.

For more details see the Keypoints class documentation.

Probs#

Probs object can be used to obtain top1 and top5 classification indices and scores.

Probs
from ultralytics import YOLO

# Load a pretrained YOLO26n-cls Classify model
model = YOLO("yolo26n-cls.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.probs)  # print the Probs object containing the detected class probabilities

Here's a table summarizing the methods and properties for the Probs class:

NameTypeDescription
cpu()MethodReturns a copy of the probs tensor on CPU memory.
numpy()MethodReturns a copy of the probs tensor as a NumPy array.
cuda()MethodReturns a copy of the probs tensor on GPU memory.
to()MethodReturns a copy of the probs tensor with the specified device and dtype.
top1Property (int)Index of the top 1 class.
top5Property (list[int])Indices of the top 5 classes.
top1confProperty (torch.Tensor)Confidence of the top 1 class.
top5confProperty (torch.Tensor)Confidences of the top 5 classes.

For more details see the Probs class documentation.

OBB#

OBB object can be used to index, manipulate, and convert oriented bounding boxes to different formats.

OBB
from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n-obb.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/boats.jpg")  # results list

# View results
for r in results:
    print(r.obb)  # print the OBB object containing the oriented detection bounding boxes

Here is a table for the OBB class methods and properties, including their name, type, and description:

NameTypeDescription
cpu()MethodMove the object to CPU memory.
numpy()MethodConvert the object to a NumPy array.
cuda()MethodMove the object to CUDA memory.
to()MethodMove the object to the specified device.
confProperty (torch.Tensor)Return the confidence values of the boxes.
clsProperty (torch.Tensor)Return the class values of the boxes.
idProperty (torch.Tensor)Return the track IDs of the boxes (if available).
xyxyProperty (torch.Tensor)Return the horizontal boxes in xyxy format.
xywhrProperty (torch.Tensor)Return the rotated boxes in xywhr format.
xyxyxyxyProperty (torch.Tensor)Return the rotated boxes in xyxyxyxy format.
xyxyxyxynProperty (torch.Tensor)Return the rotated boxes in xyxyxyxy format normalized by image size.

For more details see the OBB class documentation.

Plotting Results#

The plot() method in Results objects facilitates visualization of predictions by overlaying detected objects (such as bounding boxes, masks, keypoints, and probabilities) onto the original image. This method returns the annotated image as a NumPy array, allowing for easy display or saving.

Plotting
from PIL import Image

from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on 'bus.jpg'
results = model(["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"])  # results list

# Visualize the results
for i, r in enumerate(results):
    # Plot results image
    im_bgr = r.plot()  # BGR-order numpy array
    im_rgb = Image.fromarray(im_bgr[..., ::-1])  # RGB-order PIL image

    # Show results to screen (in supported environments)
    r.show()

    # Save results to disk
    r.save(filename=f"results{i}.jpg")

plot() Method Parameters#

The plot() method supports various arguments to customize the output:

ArgumentTypeDescriptionDefault
confboolInclude detection confidence scores.True
line_widthfloatLine width of bounding boxes. Scales with image size if None.None
font_sizefloatText font size. Scales with image size if None.None
fontstrFont name for text annotations.'Arial.ttf'
pilboolReturn image as a PIL Image object.False
imgnp.ndarray | torch.TensorAlternative image. Tensors must be contiguous HWC BGR uint8.None
kpt_radiusintRadius for drawn keypoints.5
kpt_lineboolConnect keypoints with lines.True
labelsboolInclude class labels in annotations.True
boxesboolOverlay bounding boxes on the image.True
masksboolOverlay masks on the image.True
probsboolInclude classification probabilities.True
showboolDisplay the annotated image directly using the default image viewer.False
saveboolSave the annotated image to a file specified by filename.False
filenamestrPath and name of the file to save the annotated image if save is True.None
color_modestrSpecify the color mode, e.g., 'instance' or 'class'.'class'
txt_colortuple[int, int, int]BGR text color for classification labels.(255, 255, 255)

Thread-Safe Inference#

Ensuring thread safety during inference is crucial when you are running multiple YOLO models in parallel across different threads. Thread-safe inference guarantees that each thread's predictions are isolated and do not interfere with one another, avoiding race conditions and ensuring consistent and reliable outputs.

When using YOLO models in a multi-threaded application, it's important to instantiate separate model objects for each thread or employ thread-local storage to prevent conflicts:

Thread-Safe Inference

Instantiate a single model inside each thread for thread-safe inference:

from threading import Thread

from ultralytics import YOLO

def thread_safe_predict(model, image_path):
    """Performs thread-safe prediction on an image using a locally instantiated YOLO model."""
    model = YOLO(model)
    results = model.predict(image_path)
    # Process results

# Starting threads that each have their own model instance
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image1.jpg")).start()
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image2.jpg")).start()

Streaming Source for-loop#

Here's a Python script using OpenCV (cv2) and YOLO to run inference on video frames. This script assumes you have already installed the necessary packages (opencv-python and ultralytics).

Streaming for-loop
import cv2

from ultralytics import YOLO

# Load the YOLO model
model = YOLO("yolo26n.pt")

# Open the video file
video_path = "path/to/your/video/file.mp4"
cap = cv2.VideoCapture(video_path)

# Loop through the video frames
while cap.isOpened():
    # Read a frame from the video
    success, frame = cap.read()

    if success:
        # Run YOLO inference on the frame
        results = model(frame)

        # Visualize the results on the frame
        annotated_frame = results[0].plot()

        # Display the annotated frame
        cv2.imshow("YOLO Inference", annotated_frame)

        # Break the loop if 'q' is pressed
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break
    else:
        # Break the loop if the end of the video is reached
        break

# Release the video capture object and close the display window
cap.release()
cv2.destroyAllWindows()

This script will run predictions on each frame of the video, visualize the results, and display them in a window. The loop can be exited by pressing 'q'.

What's Next#

Ready to move past a pretrained model? Confirm your task fits your problem, format your own data with the Datasets guide, then train on it.

FAQ#

  • Ultralytics YOLO is a family of state-of-the-art models for real-time object detection, instance segmentation, semantic segmentation, depth estimation, classification, pose estimation, and oriented bounding box (OBB) detection. Its predict mode runs high-speed inference on data sources such as images, videos, and live streams, with batch processing and streaming support.

  • Ultralytics YOLO can process a wide range of data sources, including individual images, videos, directories, URLs, and streams. You can specify the data source in the model.predict() call. For example, use 'image.jpg' for a local image or 'https://ultralytics.com/images/bus.jpg' for a URL. Check out the detailed examples for various inference sources in the documentation.

  • To optimize inference speed and manage memory efficiently, you can use the streaming mode by setting stream=True in the predictor's call method. The streaming mode generates a memory-efficient generator of Results objects instead of loading all frames into memory. For processing long videos or large datasets, streaming mode is particularly useful. Learn more about streaming mode.

  • The model.predict() method in YOLO supports various arguments such as conf, iou, imgsz, device, and more. These arguments allow you to customize the inference process, setting parameters like confidence thresholds, image size, and the device used for computation. Detailed descriptions of these arguments can be found in the inference arguments section.

  • Use model.embed(source) to extract feature embeddings from the second-to-last layer, or pass embed=[layer_index] to model.predict() to choose specific layers.

    from ultralytics import YOLO
    
    model = YOLO("yolo26n.pt")
    source = "https://ultralytics.com/images/bus.jpg"
    
    results = model.predict(source)  # Results objects
    embeddings = model.embed(source)  # list of torch.Tensor embeddings
  • After running inference with YOLO, the Results objects contain methods for displaying and saving annotated images. You can use methods like result.show() and result.save(filename="result.jpg") to visualize and save the results. Any missing parent directories in the filename path are created automatically (e.g., result.save("path/to/result.jpg")). For a comprehensive list of these methods, refer to the working with results section.

Comments629

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

  1. TigoresGitHub

    你好,我想问一下为什么我在推理相同的图像时,设置不同的imgsz参数,会有不同的结果。在一张图像上,有大船、小船、人。imgsz设置的值有640(默认)、1280、1980。640只能检测到大船;1280会检测到大船和小船,并且大船的置信度更高;1980还能检测到人。我很疑惑,模型的输入尺寸不是在训练的时候就已经固定了吗,这是否意味着推理的图像预处理阶段,不管我如何调整imgsz参数,模型都会将输入图像采样到640。但是现在出现的不同的结果,是为什么呢?下面是我的代码: from ultralytics import YOLO model = YOLO("/data/dxh/ultralytics/weight/yolov8s.pt")
    results = model("/data/dxh/ultralytics/datasets/test/invade_ship_cls/invade_result", imgsz=1280, save=True)

    1
    1. Glenn JocherUltralytics

      @Tigores 您好!YOLO模型在推理时会自动将输入图像缩放到您指定的imgsz参数值(而非固定为训练尺寸),更大的分辨率能保留更多细节从而提升小目标检测能力。具体原理可参考Predict模式文档中的图像尺寸与精度关系说明,这是预期行为而非异常现象。

  2. LwpZoeGitHub

    Hello, I would like to ask, my task is instance segmentation. At present, I get the predicted result is the original image superimposed label image, but the result I want is just the RGB label image, no need to superimpose the original image. Where do I need to make changes to make the result a segmented label image?

    1
    1. Glenn JocherUltralytics(edited)

      @LwpZoe to obtain only the RGB label image without the original image overlay, you can disable the overlay during visualization. Use the plot() method with boxes=False and masks=True to only display the segmentation masks. Alternatively, you can directly access result.masks.data for raw mask data and process it as needed. Refer to the Results section for more details.

    2. LwpZoeGitHub

      Found plot () in yolo-segment-main/ultralytics/engine/results.py, modified content: Def plot ( Self, Conf = True, line_width = None, font_size = None, Font = "Arial.ttf", Pil = False, Img = None, im_gpu = None, kpt_radius = 5, kpt_line = False, Labels = False, Boxes = False, Masks = True, Probs = True, Show = True, Save = True, Filename = 'result', color_mode = "class", ): Make predictions using the command line: Yolo segment predict model = runs/segment/train/weights/best.pt source=yolo-seg-main/datasets/test The result is still the original image overlay mask and box, why? Does changing plot () require retraining to get best.pt in order to predict?

    3. Glenn JocherUltralytics

      To display only the segmentation mask without overlays, modify the plot() function parameters by setting boxes=False, labels=False, and ensuring masks=True. You don't need retraining to adjust visualization settings, as the weights remain unaffected. For further details, refer to the Results.plot() documentation.

  3. User

    Hello, when I run the predict script, I predict a large amount of image data (about more than 20,000 test images). At this time, the model's predict will get stuck, and I don't generate the image of the prediction box. How can I solve this bug?

    1
    1. Paula DerrengerUltralytics

      @Stephen-Hao it sounds like you might be running into memory issues when processing a large number of images. To handle large datasets more efficiently, consider using the stream=True argument in your model.predict() call. This will create a memory-efficient generator of results, reducing the likelihood of your system getting stuck. Additionally, ensure you are using the latest version of the Ultralytics package to benefit from any recent optimizations and bug fixes. If the issue persists, please provide more details about your environment and any error messages you encounter.

    2. Paula DerrengerUltralytics

      @Stephen-Hao you're welcome! If you're experiencing issues with the model getting stuck while predicting a large number of images, try using the stream=True argument in your model.predict() call. This will help manage memory more efficiently by processing images one at a time instead of loading all at once. Also, ensure you're using the latest version of the Ultralytics package. If the problem persists, please provide more details about your setup and any error messages you encounter.

  4. Johanna-JonesGitHub

    Hey, Is there a way to get the MAP precision, IOU and other metrics for the test images you might give the model?

    I have images and the ground truth for the test images but not sure how to get the same metrics for the PREDICT mode

    Thank you!

    1
    1. Johanna-JonesGitHub

      For clarification my pipeline is currently train> valid with val parameter set to false. I then pass one image at a time to the Yolov8 model in the PREDICT mode

    2. Paula DerrengerUltralytics

      Hey there!

      For evaluating your model with metrics like mAP, precision, and IOU on your test images, you should use the Val mode rather than the Predict mode. The Val mode allows you to validate your model on a dataset and provides comprehensive metrics, including the ones you're interested in. Here's an example on how to do it:

      from ultralytics import YOLO
      
      # Assuming 'coco128.yaml' is your dataset configuration file that includes your test data path
      # and that 'your_model.pt' is the trained model you want to evaluate
      model = YOLO('path/to/your_model.pt')
      
      # Validate the model, this will automatically calculate mAP, IOU, and other metrics
      results = model.val(data='path/to/your_dataset_config.yaml')

      Remember to adjust 'path/to/your_model.pt' and 'path/to/your_dataset_config.yaml' to the actual paths of your model and dataset configuration file.

      In your YAML dataset configuration file, make sure to correctly specify the path to your test images and annotations. This way, YOLOv8 will know how to find your test data and corresponding ground truth for evaluation.

      If you have any more questions, feel free to ask. Good luck with your model evaluation! 🚀

  5. GUPABE10GitHub

    how to ignore printing results after inference: 0: 384x640 10 persons, 1 sports ball, 4080.4ms Speed: 12.3ms preprocess, 4080.4ms inference, 1.7ms postprocess per image at shape (1, 3, 384, 640)

    1
    1. Glenn JocherUltralytics

      To disable printing inference results after running predictions, you can use the verbose=False argument in your predict() function. This will prevent the printout of inference times and detected objects. Here's a quick example on how to do it:

      from ultralytics import YOLO
      
      # Load your YOLOv8 model
      model = YOLO('yolov8n.pt')  
      
      # Run inference with verbose=False
      results = model.predict('path/to/your/image.jpg', verbose=False)

      This should keep your console output clean while still performing inference. 😊

    2. GUPABE10GitHub

      Is it the same if I use:

      results = model('path/to/your/image.jpg')

      just as mentioned in the example in this tutorial.

    3. Glenn JocherUltralytics

      @GUPABE10 hi there!

      Yes, using results = model('path/to/your/image.jpg') is perfectly fine and aligns with the examples provided in the tutorial. This command will run inference on the specified image and return the results as a list of Results objects.

      If you want to avoid printing the detailed inference results (like the number of detected objects and processing times), you can use the verbose=False argument:

      from ultralytics import YOLO
      
      # Load a pretrained YOLOv8n model
      model = YOLO("yolov8n.pt")
      
      # Run inference on an image without printing detailed results
      results = model.predict('path/to/your/image.jpg', verbose=False)

      This will keep your console output clean while still performing the inference. If you have any more questions or need further assistance, feel free to ask! 😊

    4. Glenn JocherUltralytics

      Hi there!

      Great question! The difference between model.predict() and model() lies in their usage and flexibility:

      1. model.predict():

        • This method is explicitly designed for running predictions and allows you to pass various arguments to customize the inference process.
        • You can specify parameters like save, imgsz, conf, device, and more to control the behavior of the prediction.
        • Example:
          from ultralytics import YOLO
          
          # Load a pretrained YOLOv8n model
          model = YOLO("yolov8n.pt")
          
          # Run inference with custom arguments
          results = model.predict("path/to/image.jpg", save=True, imgsz=320, conf=0.5)
      2. model():

        • This is a shorthand method that calls the predict() function internally with default settings.
        • It is useful for quick predictions without needing to specify additional parameters.
        • Example:
          from ultralytics import YOLO
          
          # Load a pretrained YOLOv8n model
          model = YOLO("yolov8n.pt")
          
          # Run inference with default settings
          results = model("path/to/image.jpg")

      Both methods will return a list of Results objects, which you can then process as needed. If you need more control over the prediction process, model.predict() is the way to go. For quick and straightforward predictions, model() is convenient.

      Feel free to check out the Ultralytics documentation on prediction for more details and examples.

      Happy coding! 😊

  6. amani784GitHub

    Hello @glenn-jocher, i have question, my inputs are videos, if i use vid-stride , can i use imgsz with it ?

    1. Glenn JocherUltralytics

      Yes—vid_stride (frame skipping) and imgsz (inference resize) are independent, so you can use them together on video sources; imgsz will be applied to the frames that are actually processed (see the Predict mode inference arguments).

      yolo predict model=yolo26n.pt source=video.mp4 vid_stride=2 imgsz=640
      from ultralytics import YOLO
      
      model = YOLO("yolo26n.pt")
      for r in model.predict("video.mp4", vid_stride=2, imgsz=640, stream=True):
          pass
      1
    2. amani784GitHub

      Thank you for your help. I have another question: if I don’t define imgsz in predict, will it resize the image to 640 by default? I have multiple inputs with different resolutions, so I can’t specify a single value for imgsz in .predict or even during ONNX export, because sometimes the input resolution is larger than imgsz.

    3. Glenn JocherUltralytics

      Yes—if you don’t pass imgsz to predict(), it uses the default imgsz=640 and will letterbox/resize each frame/image to that inference size (so larger inputs are downscaled, smaller are upscaled); for mixed-resolution sources you can either leave the default or set a larger imgsz for more detail (GPU memory permitting) as described in the predict settings defaults.

      If you need an ONNX that can accept varying input shapes at runtime, export with dynamic shapes enabled (then your runtime can feed different H×W sizes):

      yolo export model=yolo26n.pt format=onnx dynamic=True
      from ultralytics import YOLO
      
      model = YOLO("yolo26n.pt")
      model.export(format="onnx", dynamic=True)

      Feel free to drop the exact input resolutions (and whether this is video-only) here in the discussion and we can suggest a good imgsz strategy for your case.

      1
    4. amani784GitHub

      Thank you so much ,but for tensorRT export , the model can't accept varying input shapes and i was obliged to put imgsz or my videos have different resolutions and i can't put one imgsz value that can fit all the resolutions. Is there any other solution?

    5. Glenn JocherUltralytics

      Yes—TensorRT doesn’t have to be fixed-shape: export your .engine with dynamic=True so the runtime can accept varying input shapes (you can then choose imgsz per run/video), see the Export mode docs and the TensorRT integration guide.

      yolo export model=yolo26n.pt format=engine dynamic=True

      If you need peak throughput and your resolutions vary a lot, the usual workaround is exporting 2–3 fixed engines at common imgsz values and selecting the closest one at runtime.

      1
  7. Asshok1GitHub

    Hey @glenn-jocher, I’m trying to integrate a TensorRT-optimized YOLO model (.engine) with SAHI (Slicing Aided Hyper Inference) for efficient large-image inference, but I’m facing difficulties making them work together correctly as .engine is not accepted in sahi, can you help in providing the complete code for integrating tensorRT with sahi.

    1. Glenn JocherUltralytics

      SAHI’s built-in Ultralytics integration (model_type="ultralytics") currently expects PyTorch weights like *.pt, so a TensorRT *.engine file won’t load through SAHI as-is; the supported path is to use SAHI with *.pt per the SAHI tiled inference guide, or run the TensorRT engine directly with Ultralytics per the TensorRT export/inference guide. If you specifically need SAHI slicing + a *.engine, you’ll need a custom SAHI DetectionModel adapter around Ultralytics’ TensorRT predictor (best tracked upstream in the SAHI repository); please paste your Ultralytics/SAHI versions and a minimal repro here in the discussion so we can advise on the cleanest adapter approach.

      # SAHI (supported): Ultralytics *.pt + slicing
      from sahi import AutoDetectionModel
      from sahi.predict import get_sliced_prediction
      
      detection_model = AutoDetectionModel.from_pretrained(
          model_type="ultralytics",
          model_path="best.pt",
          confidence_threshold=0.25,
          device="cuda:0",
      )
      
      result = get_sliced_prediction(
          "large.jpg",
          detection_model,
          slice_height=640,
          slice_width=640,
          overlap_height_ratio=0.2,
          overlap_width_ratio=0.2,
      )
      # TensorRT (supported): Ultralytics *.engine inference (no SAHI wrapper)
      from ultralytics import YOLO
      
      model = YOLO("best.engine")
      results = model.predict("large.jpg", device=0, imgsz=640)
  8. hanchaoyuanGitHub

    hello! I used the YOLO11-pose model to estimate the key points of people in the automotive production workshop. However, the model often identified vehicles, hoists and other equipment as humans and calculated the key points, resulting in a relatively high false alarm rate. My question is: How can we prevent the model from identifying other objects and reduce the false alarm rate?

    1. Glenn JocherUltralytics

      For workshop false positives with pose models, the quickest lever is raising the prediction threshold (and optionally increasing imgsz for better person discrimination), but the most reliable fix is fine-tuning on your own workshop data with “hard negative” images (frames with vehicles/hoists but no people) so the model learns your background; see the inference args in the predict mode docs.

      yolo pose predict model=yolo11n-pose.pt source=path/to/video.mp4 conf=0.6 imgsz=960

      If you paste your exact command, plus a couple representative frames (people + false positives) here in the discussion, we can suggest tighter settings or a training setup (and for new work, try a YOLO26 pose checkpoint as it’s generally stronger out of the box).

  9. d5423197GitHub

    Hi there,

    If no boxes/masks detected by the model, what will be the output of model inference. (results = model(["image1.jpg", "image2.jpg"]) #)

    I want to deal with the edge case.

  10. max-dev-14GitHub

    How to predict and show or save prediction YOLO (custom model) for video fragment?