docs/macros/predict-args.md
| 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.7 | 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 pad to the full imgsz. See Fixed shape vs minimum rectangle. |
quantize | int or str | None | Inference precision: 16/"fp16" enables FP16 inference on supported GPUs; 32/"fp32"/unset is FP32. 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. |
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. |
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. For end-to-end models (YOLO26, 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. |
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/Windows x86 CPUs, False disables it, and True requests it on supported x86 CPU or CUDA devices. ARM64, MPS, SAM predictors, CPUs without oneDNN, and exported formats such as TensorRT and ONNX remain unchanged. |
end2end | bool | None | Overrides the end-to-end mode in YOLO models that support NMS-free inference (YOLO26, YOLOv10). Setting it to False lets you run prediction using the traditional NMS pipeline, additionally allowing you to make use of the iou argument. See the End-to-End Detection guide for details. |