Model Prediction with Ultralytics YOLO
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#
| Manufacturing | Sports | Safety |
|---|---|---|
| Vehicle Spare Parts Detection | Football Player Detection | People 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
Resultsobjects. Enable this by settingstream=Truein the predictor's call method. Unlike the default behavior (stream=False), which returns a list containing all results,stream=Trueyields 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:
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 diskInference 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.
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.
| Source | Example | Type | Notes |
|---|---|---|---|
| image | 'image.jpg' | str or Path | Single image file. |
| URL | 'https://ultralytics.com/images/bus.jpg' | str | URL to an image. |
| screenshot ✅ | 'screen' | str | Capture the screen continuously until stopped. |
| PIL | Image.open('image.jpg') | PIL.Image | HWC format with RGB channels. |
| OpenCV | cv2.imread('image.jpg') | np.ndarray | HWC format with BGR channels uint8 (0-255). |
| NumPy | np.zeros((640,1280,3)) | np.ndarray | HWC format with BGR channels uint8 (0-255). |
| torch | torch.zeros(16,3,320,640) | torch.Tensor | BCHW format with RGB channels float32 (0.0-1.0). |
| CSV | 'sources.csv' | str or Path | CSV file containing paths to images, videos, or directories. |
| video ✅ | 'video.mp4' | str or Path | Video file in formats like MP4, AVI, etc. |
| directory ✅ | 'path/' | str or Path | Path to a directory containing images or videos. |
| glob ✅ | 'path/*.jpg' | str | Glob pattern to match multiple files. Use the * character as a wildcard. |
| YouTube ✅ | 'https://youtu.be/LNwODJXcvt4' | str | URL to a YouTube video. |
| stream ✅ | 'rtsp://example.com/media.mp4' | str | URL 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 ✅ | 0 | int | Index of the connected camera device to run inference on. |
Below are code examples for using each source type:
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 objectsInference 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=640becomes a square target(640, 640)after stride rounding. - A tuple
imgsz=(384, 672)sets a rectangular target. Withrect=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.
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:
| Argument | Type | Default | Description |
|---|---|---|---|
source | str or int or None | None | Specifies 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. |
conf | float | 0.25 | Sets the minimum confidence threshold for detections. Objects detected with confidence below this threshold will be disregarded. Adjusting this value can help reduce false positives. |
iou | float | 0.5 | Intersection Over Union (IoU) threshold for Non-Maximum Suppression (NMS). Lower values result in fewer detections by eliminating overlapping boxes, useful for reducing duplicates. |
imgsz | int or tuple | 640 | Letterbox 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. |
rect | bool | True | If 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. |
quantize | int or str | None | Inference 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. |
device | str | None | Specifies 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. |
dnn | bool | False | If True, uses the OpenCV DNN module instead of ONNX Runtime for ONNX model inference. |
data | str | None | Path 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. |
batch | int | 1 | Specifies 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. |
tile | bool or int | False | Runs fixed tiled inference and returns outputs in original-image coordinates. True uses imgsz; a positive int sets tile size. See High Resolution Tiling. |
max_det | int | 300 | Maximum 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_stride | int | 1 | Frame 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_buffer | bool | False | Determines 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. |
visualize | bool | False | Saves 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. |
augment | bool | False | Enables test-time augmentation (TTA) for predictions, potentially improving detection robustness at the cost of inference speed. Only available for Ultralytics PyTorch models. |
agnostic_nms | bool | False | Enables 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. |
classes | list[int] | None | Filters 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_masks | bool | False | Returns 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. |
embed | list[int] | None | Specifies 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. |
project | str | None | Name 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. |
name | str | None | Name of the prediction run. Used for creating a subdirectory within the project folder, where prediction outputs are stored if save is enabled. |
stream | bool | False | Enables 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. |
verbose | bool | True | Controls whether to display detailed inference logs in the terminal, providing real-time feedback on the prediction process. |
compile | bool or str | False | Enables 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_last | bool | None | Uses 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. |
nms | bool, optional | None | Runs 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:
| Argument | Type | Default | Description |
|---|---|---|---|
show | bool | False | If True, displays the annotated images or videos in a window. Useful for immediate visual feedback during development or testing. |
save | bool | False or True | Enables 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_frames | bool | False | When processing videos, saves individual frames as images. Useful for extracting specific frames or for detailed frame-by-frame analysis. |
save_txt | bool | False | Saves 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_conf | bool | False | Includes confidence scores in the saved text files. Enhances the detail available for post-processing and analysis. |
save_crop | bool | False | Saves cropped images of detections. Useful for dataset augmentation, analysis, or creating focused datasets for specific objects. |
show_labels | bool | True | Displays labels for each detection in the visual output. Provides immediate understanding of detected objects. |
show_conf | bool | True | Displays the confidence score for each detection alongside the label. Gives insight into the model's certainty for each detection. |
show_boxes | bool | True | Draws bounding boxes around detected objects. Essential for visual identification and location of objects in images or video frames. |
line_width | int or None | None | Specifies 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:
| Format | unset | cpu | 0 or cuda:0 | mps | xpu | npu |
|---|---|---|---|---|---|---|
PyTorch .pt, TorchScript | CUDA GPU, else CPU | CPU | NVIDIA GPU | Apple GPU | Intel GPU | Huawei Ascend NPU |
| ONNX | CUDA GPU, else CPU | CPU | NVIDIA GPU (CUDA), AMD GPU (MIGraphX) | Core ML | - | - |
| TensorRT | NVIDIA GPU | NVIDIA GPU | NVIDIA GPU | - | - | - |
| OpenVINO | OpenVINO AUTO | Intel CPU | - | - | Intel GPU (xpu:1 is OpenVINO GPU.1) | Intel NPU |
| LiteRT | CPU | CPU | - | - | Intel GPU through the OpenVINO plugin | Intel NPU through the OpenVINO plugin |
| PaddlePaddle | CUDA GPU, else CPU | CPU | NVIDIA 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.
from ultralytics import YOLO
model = YOLO("yolo26n_openvino_model/")
results = model("https://ultralytics.com/images/bus.jpg", device="npu") # Intel NPUImage 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.
HEIC/HEIF formats require pi-heif, which is installed automatically on first use. AVIF is supported natively by Pillow.
| Image Suffixes | Example Predict Command | Reference |
|---|---|---|
.avif | yolo predict source=image.avif | AV1 Image File Format |
.bmp | yolo predict source=image.bmp | Microsoft BMP File Format |
.dng | yolo predict source=image.dng | Adobe DNG |
.heic | yolo predict source=image.heic | High Efficiency Image Format |
.heif | yolo predict source=image.heif | High Efficiency Image Format |
.jp2 | yolo predict source=image.jp2 | JPEG 2000 |
.jpeg | yolo predict source=image.jpeg | JPEG |
.jpg | yolo predict source=image.jpg | JPEG |
.mpo | yolo predict source=image.mpo | Multi Picture Object |
.png | yolo predict source=image.png | Portable Network Graphics |
.tif | yolo predict source=image.tif | Tag Image File Format |
.tiff | yolo predict source=image.tiff | Tag Image File Format |
.webp | yolo predict source=image.webp | WebP |
Videos#
The below table contains valid Ultralytics video formats.
| Video Suffixes | Example Predict Command | Reference |
|---|---|---|
.asf | yolo predict source=video.asf | Advanced Systems Format |
.avi | yolo predict source=video.avi | Audio Video Interleave |
.gif | yolo predict source=video.gif | Graphics Interchange Format |
.m4v | yolo predict source=video.m4v | MPEG-4 Part 14 |
.mkv | yolo predict source=video.mkv | Matroska |
.mov | yolo predict source=video.mov | QuickTime File Format |
.mp4 | yolo predict source=video.mp4 | MPEG-4 Part 14 - Wikipedia |
.mpeg | yolo predict source=video.mpeg | MPEG-1 Part 2 |
.mpg | yolo predict source=video.mpg | MPEG-1 Part 2 |
.ts | yolo predict source=video.ts | MPEG Transport Stream |
.wmv | yolo predict source=video.wmv | Windows Media Video |
.webm | yolo predict source=video.webm | WebM Project |
Working with Results#
All Ultralytics predict() calls will return a list of Results objects:
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 inferenceResults objects have the following attributes:
| Attribute | Type | Description |
|---|---|---|
orig_img | np.ndarray | The original image as a NumPy array. |
orig_shape | tuple | The original image shape in (height, width) format. |
boxes | Boxes, optional | A Boxes object containing the detection bounding boxes. |
masks | Masks, optional | A Masks object containing the detection masks. |
probs | Probs, optional | A Probs object containing probabilities of each class for classification task. |
keypoints | Keypoints, optional | A Keypoints object containing detected keypoints for each object. |
obb | OBB, optional | An OBB object containing oriented bounding boxes. |
semantic_mask | SemanticMask, optional | A SemanticMask object containing a dense per-pixel class map. |
depth | DepthMap, optional | A DepthMap object containing a dense per-pixel depth map. |
speed | dict | A dictionary of preprocess, inference, and postprocess speeds in milliseconds per image. |
names | dict | A dictionary mapping class indices to class names. |
path | str | The path to the image file. |
save_dir | str, optional | Directory 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.
| Attribute | Type | Shape | Description |
|---|---|---|---|
result.boxes | Boxes | (N) | Detection boxes. |
result.boxes.data | torch.float32 | (N,6/7) | Raw [x1,y1,x2,y2,conf,cls], plus optional track ID. |
result.boxes.xyxy | torch.float32 | (N,4) | xyxy pixel boxes. |
result.boxes.conf | torch.float32 | (N,) | Confidence scores. |
result.boxes.cls | torch.float32 | (N,) | Class IDs; cast to int for names. |
Results objects have the following methods:
| Method | Return Type | Description |
|---|---|---|
update() | None | Updates the Results object with new data such as boxes, masks, probs, obb, keypoints, semantic masks, or depth. |
cpu() | Results | Returns a copy of the Results object with all tensors moved to CPU memory. |
numpy() | Results | Returns a copy of the Results object with all tensors converted to NumPy arrays. |
cuda() | Results | Returns a copy of the Results object with all tensors moved to GPU memory. |
to() | Results | Returns a copy of the Results object with tensors moved to specified device and dtype. |
new() | Results | Creates a new Results object with the same image, path, names, and speed attributes. |
plot() | np.ndarray | Plots detection results on an input BGR image and returns the annotated image. |
show() | None | Displays the image with annotated inference results. |
save() | str | Saves annotated inference results image to file and returns the filename. |
verbose() | str | Returns a log string for each task, detailing detection and classification outcomes. |
save_txt() | str | Saves detection results to a text file and returns the path to the saved file. |
save_crop() | None | Saves cropped detection images to specified directory. |
summary() | List[Dict[str, Any]] | Converts inference results to a summarized dictionary with optional normalization. |
to_df() | DataFrame | Converts detection results to a Polars DataFrame. |
to_csv() | str | Converts detection results to CSV format. |
to_json() | str | Converts 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.
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 boxesHere is a table for the Boxes class methods and properties, including their name, type, and description:
| Name | Type | Description |
|---|---|---|
cpu() | Method | Move the object to CPU memory. |
numpy() | Method | Convert the object to a NumPy array. |
cuda() | Method | Move the object to CUDA memory. |
to() | Method | Move the object to the specified device. |
xyxy | Property (torch.Tensor) | Return the boxes in xyxy format. |
conf | Property (torch.Tensor) | Return the confidence values of the boxes. |
cls | Property (torch.Tensor) | Return the class values of the boxes. |
id | Property (torch.Tensor) | Return the track IDs of the boxes (if available). |
xywh | Property (torch.Tensor) | Return the boxes in xywh format. |
xyxyn | Property (torch.Tensor) | Return the boxes in xyxy format normalized by original image size. |
xywhn | Property (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.
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 masksHere is a table for the Masks class methods and properties, including their name, type, and description:
| Name | Type | Description |
|---|---|---|
data | Property (torch.Tensor) | torch.uint8 binary mask tensor with shape (N,H,W) and values 0 or 1. |
cpu() | Method | Returns the masks tensor on CPU memory. |
numpy() | Method | Returns the masks tensor as a NumPy array. |
cuda() | Method | Returns the masks tensor on GPU memory. |
to() | Method | Returns the masks tensor with the specified device and dtype. |
xyn | Property (list[np.ndarray]) | A list of normalized mask polygons. |
xy | Property (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.
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| Name | Type | Description |
|---|---|---|
data | Property (torch.Tensor) | Class-ID map with shape (H,W). Dtype is torch.uint8, torch.int16, or torch.int32, selected by class count. |
shape | Property (tuple) | Shape of the class map, usually matching result.orig_shape. |
cpu() | Method | Returns the semantic mask tensor on CPU memory. |
numpy() | Method | Returns the semantic mask tensor as a NumPy array. |
cuda() | Method | Returns the semantic mask tensor on GPU memory. |
to() | Method | Returns the semantic mask tensor with the specified device and dtype. |
Keypoints#
Keypoints object can be used to index, manipulate and normalize coordinates.
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 keypointsHere is a table for the Keypoints class methods and properties, including their name, type, and description:
| Name | Type | Description |
|---|---|---|
cpu() | Method | Returns the keypoints tensor on CPU memory. |
numpy() | Method | Returns the keypoints tensor as a NumPy array. |
cuda() | Method | Returns the keypoints tensor on GPU memory. |
to() | Method | Returns the keypoints tensor with the specified device and dtype. |
xyn | Property (torch.Tensor) | Normalized keypoint coordinates with shape (N,K,2). |
xy | Property (torch.Tensor) | Keypoint coordinates in pixels with shape (N,K,2). |
conf | Property (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.
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 probabilitiesHere's a table summarizing the methods and properties for the Probs class:
| Name | Type | Description |
|---|---|---|
cpu() | Method | Returns a copy of the probs tensor on CPU memory. |
numpy() | Method | Returns a copy of the probs tensor as a NumPy array. |
cuda() | Method | Returns a copy of the probs tensor on GPU memory. |
to() | Method | Returns a copy of the probs tensor with the specified device and dtype. |
top1 | Property (int) | Index of the top 1 class. |
top5 | Property (list[int]) | Indices of the top 5 classes. |
top1conf | Property (torch.Tensor) | Confidence of the top 1 class. |
top5conf | Property (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.
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 boxesHere is a table for the OBB class methods and properties, including their name, type, and description:
| Name | Type | Description |
|---|---|---|
cpu() | Method | Move the object to CPU memory. |
numpy() | Method | Convert the object to a NumPy array. |
cuda() | Method | Move the object to CUDA memory. |
to() | Method | Move the object to the specified device. |
conf | Property (torch.Tensor) | Return the confidence values of the boxes. |
cls | Property (torch.Tensor) | Return the class values of the boxes. |
id | Property (torch.Tensor) | Return the track IDs of the boxes (if available). |
xyxy | Property (torch.Tensor) | Return the horizontal boxes in xyxy format. |
xywhr | Property (torch.Tensor) | Return the rotated boxes in xywhr format. |
xyxyxyxy | Property (torch.Tensor) | Return the rotated boxes in xyxyxyxy format. |
xyxyxyxyn | Property (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.
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:
| Argument | Type | Description | Default |
|---|---|---|---|
conf | bool | Include detection confidence scores. | True |
line_width | float | Line width of bounding boxes. Scales with image size if None. | None |
font_size | float | Text font size. Scales with image size if None. | None |
font | str | Font name for text annotations. | 'Arial.ttf' |
pil | bool | Return image as a PIL Image object. | False |
img | np.ndarray | torch.Tensor | Alternative image. Tensors must be contiguous HWC BGR uint8. | None |
kpt_radius | int | Radius for drawn keypoints. | 5 |
kpt_line | bool | Connect keypoints with lines. | True |
labels | bool | Include class labels in annotations. | True |
boxes | bool | Overlay bounding boxes on the image. | True |
masks | bool | Overlay masks on the image. | True |
probs | bool | Include classification probabilities. | True |
show | bool | Display the annotated image directly using the default image viewer. | False |
save | bool | Save the annotated image to a file specified by filename. | False |
filename | str | Path and name of the file to save the annotated image if save is True. | None |
color_mode | str | Specify the color mode, e.g., 'instance' or 'class'. | 'class' |
txt_color | tuple[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:
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).
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=Truein the predictor's call method. The streaming mode generates a memory-efficient generator ofResultsobjects 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 asconf,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 passembed=[layer_index]tomodel.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 embeddingsAfter running inference with YOLO, the
Resultsobjects contain methods for displaying and saving annotated images. You can use methods likeresult.show()andresult.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.
Tigores
你好,我想问一下为什么我在推理相同的图像时,设置不同的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
Glenn JocherUltralytics@Tigores 您好!YOLO模型在推理时会自动将输入图像缩放到您指定的imgsz参数值(而非固定为训练尺寸),更大的分辨率能保留更多细节从而提升小目标检测能力。具体原理可参考Predict模式文档中的图像尺寸与精度关系说明,这是预期行为而非异常现象。
LwpZoe
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
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 withboxes=Falseandmasks=Trueto only display the segmentation masks. Alternatively, you can directly accessresult.masks.datafor raw mask data and process it as needed. Refer to the Results section for more details.LwpZoe
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?
Glenn JocherUltralyticsTo display only the segmentation mask without overlays, modify the
plot()function parameters by settingboxes=False,labels=False, and ensuringmasks=True. You don't need retraining to adjust visualization settings, as the weights remain unaffected. For further details, refer to the Results.plot() documentation.
UserHello, 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
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=Trueargument in yourmodel.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.
UserYes, Thank you a lot.
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=Trueargument in yourmodel.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.
Johanna-Jones
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!
1Johanna-Jones
For clarification my pipeline is currently train> valid with
valparameter set to false. I then pass one image at a time to the Yolov8 model in the PREDICT mode
Paula DerrengerUltralyticsHey there!
For evaluating your model with metrics like mAP, precision, and IOU on your test images, you should use the
Valmode rather than thePredictmode. TheValmode 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! 🚀
GUPABE10
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
Glenn JocherUltralyticsTo disable printing inference results after running predictions, you can use the
verbose=Falseargument in yourpredict()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. 😊
GUPABE10
Is it the same if I use:
results = model('path/to/your/image.jpg')
just as mentioned in the example in this tutorial.
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 ofResultsobjects.If you want to avoid printing the detailed inference results (like the number of detected objects and processing times), you can use the
verbose=Falseargument: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! 😊
GUPABE10
What is the difference between model.predict() and model()?
Glenn JocherUltralyticsHi there!
Great question! The difference between
model.predict()andmodel()lies in their usage and flexibility:-
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)
-
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")
- This is a shorthand method that calls the
Both methods will return a list of
Resultsobjects, 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! 😊
-
amani784
Hello @glenn-jocher, i have question, my inputs are videos, if i use vid-stride , can i use imgsz with it ?
Glenn JocherUltralyticsYes—
vid_stride(frame skipping) andimgsz(inference resize) are independent, so you can use them together on video sources;imgszwill 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=640from ultralytics import YOLO model = YOLO("yolo26n.pt") for r in model.predict("video.mp4", vid_stride=2, imgsz=640, stream=True): pass1amani784
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.
Glenn JocherUltralyticsYes—if you don’t pass
imgsztopredict(), it uses the defaultimgsz=640and 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 largerimgszfor 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=Truefrom 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
imgszstrategy for your case.1amani784
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?
Glenn JocherUltralyticsYes—TensorRT doesn’t have to be fixed-shape: export your
.enginewithdynamic=Trueso the runtime can accept varying input shapes (you can then chooseimgszper run/video), see the Export mode docs and the TensorRT integration guide.yolo export model=yolo26n.pt format=engine dynamic=TrueIf you need peak throughput and your resolutions vary a lot, the usual workaround is exporting 2–3 fixed engines at common
imgszvalues and selecting the closest one at runtime.1
Asshok1
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.
Glenn JocherUltralyticsSAHI’s built-in Ultralytics integration (
model_type="ultralytics") currently expects PyTorch weights like*.pt, so a TensorRT*.enginefile won’t load through SAHI as-is; the supported path is to use SAHI with*.ptper 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 SAHIDetectionModeladapter 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)
hanchaoyuan
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?
Glenn JocherUltralyticsFor workshop false positives with pose models, the quickest lever is raising the prediction threshold (and optionally increasing
imgszfor 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=960If 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).
d5423197
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.
max-dev-14
How to predict and show or save prediction YOLO (custom model) for video fragment?
