The YOLOv8 IoU threshold controls how strongly overlapping bounding boxes are treated during prediction post-processing and validation. IoU, or Intersection over Union, measures the amount of overlap between two bounding boxes. In Ultralytics prediction mode, the iou argument is primarily used as the IoU threshold for Non-Maximum Suppression, where overlapping predictions are filtered to reduce duplicate detections.
It is important not to confuse the configurable inference iou value with the IoU thresholds used to calculate mAP. For example, mAP50 evaluates Average Precision at IoU 0.50, while mAP50-95 averages AP across IoU thresholds from 0.50 to 0.95. Changing the NMS iou setting does not redefine those standard mAP thresholds.
Introduction to YOLOv8 IoU Threshold
Object detection models often generate several bounding boxes around the same object. These predictions may have different confidence scores and slightly different coordinates. YOLOv8 therefore needs a method for deciding which boxes should be retained and which should be removed.
Intersection over Union provides a numerical way to measure how similar two boxes are spatially. If two detections overlap strongly, their IoU will be high. If they barely overlap, IoU will be low.
A simplified example is:
Box A
+
Box B
↓
Calculate overlap
↓
IoU score
The score ranges from:
0.0
meaning no overlap, to:
1.0
meaning identical box regions.
YOLOv8 uses IoU in several parts of evaluation and post-processing. During inference, an IoU threshold helps Non-Maximum Suppression decide whether overlapping detections should be suppressed. During validation, IoU also plays a fundamental role in matching predictions against ground-truth boxes and calculating AP and mAP metrics.
Because these are different uses of IoU, the correct threshold depends on what you are configuring.
What Is IoU in YOLOv8?
IoU stands for Intersection over Union. It measures the spatial overlap between two bounding boxes.
In YOLOv8, IoU is important because object detection requires accurate localization in addition to correct class prediction.
A prediction that identifies the correct class but places the bounding box far away from the real object should not be considered a successful detection.
Intersection Over Union Explained
The IoU formula is:
IoU =
Area of Intersection
────────────────────
Area of Union
Suppose two bounding boxes overlap considerably.
The intersection is the area shared by both boxes.
The union is the total area covered by either box.
Conceptually:
Predicted Box
∩
Ground Truth Box
↓
Shared Area
If the boxes are identical:
IoU = 1.0
If they do not overlap:
IoU = 0.0
Intermediate values indicate partial overlap.
How IoU Measures Bounding Box Overlap
Consider:
Ground Truth Box
100 × 100 pixels
and a prediction that closely matches its location.
The shared area may be large compared with the total union, giving:
IoU = 0.85
A poorly aligned prediction may instead produce:
IoU = 0.30
Higher IoU generally means better localization.
This is why IoU appears in metrics such as:
mAP50
mAP75
mAP50-95
where increasingly strict IoU requirements test bounding-box quality.
What Is the IoU Threshold in YOLOv8?
An IoU threshold is a cutoff used to make a decision based on overlap.
For example:
IoU >= threshold
→ boxes considered sufficiently overlapping
or:
IoU < threshold
→ boxes treated as sufficiently different
The exact interpretation depends on the stage of the YOLOv8 pipeline.
During NMS, the threshold determines how much overlap is allowed before a lower-confidence duplicate is suppressed.
During metric calculation, specific IoU thresholds define how strict localization matching should be.
Role of IoU During Detection
During inference, the model may produce:
Box A confidence = 0.92
Box B confidence = 0.85
for the same object.
Suppose:
IoU(A, B) = 0.80
If the NMS IoU threshold is:
0.50
these boxes overlap beyond the threshold, so NMS will generally keep the higher-confidence box and suppress the lower-confidence duplicate.
Ultralytics exposes the inference iou parameter specifically as the IoU threshold used by NMS.
How the Threshold Affects Prediction Matching
The threshold determines how aggressively overlapping detections are considered redundant.
A lower NMS threshold means boxes need less overlap before suppression begins.
A higher threshold allows boxes to overlap more before one is removed.
Conceptually:
Low NMS IoU
→ aggressive suppression
High NMS IoU
→ more overlapping boxes retained
This distinction becomes important in crowded scenes where several legitimate objects may be close together.
How YOLOv8 Uses IoU During Validation
Validation uses IoU to determine whether model predictions sufficiently overlap ground-truth objects.
This matching step allows YOLOv8 to determine true positives, false positives, and false negatives.
Ultralytics detection validation computes box IoU when matching predictions with labels and then calculates metrics from the resulting matches.
Matching Predictions with Ground Truth
Suppose the ground-truth box represents a car.
YOLOv8 predicts:
Class: car
Confidence: 0.91
The predicted box is compared with the real box.
If the overlap satisfies the metric’s required IoU threshold, the prediction may count as a correct detection, assuming the class is also correct and the match is valid.
Conceptually:
Prediction
↓
Calculate IoU
↓
Compare with Ground Truth
↓
Enough overlap?
↙ ↘
Yes No
↓ ↓
Possible TP Not matched
True Positive and False Positive Decisions
A valid true positive generally requires:
correct class
+
sufficient bounding-box overlap
+
valid one-to-one match
If the box is poorly localized, the prediction may fail at a stricter IoU threshold even if the predicted class is correct.
This explains why a detector can achieve strong mAP50 but weaker mAP75 or mAP50-95.
At higher IoU thresholds, localization must be more accurate.
IoU and mAP Calculation
YOLOv8 commonly reports:
mAP50
which means mean Average Precision at:
IoU = 0.50
It also reports:
mAP50-95
which averages AP across thresholds:
0.50
0.55
0.60
...
0.95
Ultralytics metrics code explicitly defines AP at IoU 0.50 and AP averaged across IoU thresholds from 0.50 to 0.95.
This is separate from the iou parameter used for NMS.
IoU Threshold in Non-Maximum Suppression
Non-Maximum Suppression, or NMS, removes redundant predictions that overlap strongly.
This is one of the most important practical uses of the configurable iou argument during YOLOv8 inference.
Ultralytics’ current NMS API exposes:
iou_thres
as the IoU threshold used for filtering overlapping boxes.
Removing Overlapping Predictions
Suppose YOLOv8 predicts three boxes around the same vehicle:
Box A: confidence 0.94
Box B: confidence 0.87
Box C: confidence 0.72
If their IoUs are high, NMS keeps the strongest prediction and suppresses overlapping duplicates.
Conceptually:
Multiple predictions
↓
Sort by confidence
↓
Keep strongest box
↓
Compare overlaps
↓
Suppress excessive overlap
This produces a cleaner final output.
Effect of Low IoU Threshold
A low NMS IoU threshold performs more aggressive suppression.
For example:
iou=0.3
means two boxes do not need to overlap very strongly before one may be removed.
Benefits can include:
- fewer duplicate boxes,
- cleaner output,
- reduced redundant detections.
However, this can become problematic when two real objects overlap.
For example:
Person A
overlaps
Person B
If the threshold is too low, one legitimate detection may be suppressed.
Effect of High IoU Threshold
A higher value such as:
iou=0.8
allows much more overlap before NMS removes a lower-confidence box.
This can help retain separate detections in crowded scenes.
However, it may also allow duplicate boxes around the same object to survive.
Conceptually:
High IoU threshold
→ less aggressive suppression
→ more overlapping detections retained
The correct setting therefore depends on scene density and object overlap.
How to Set IoU Threshold in YOLOv8
Ultralytics exposes iou as a configurable prediction and validation argument.
During prediction, it directly controls the NMS overlap threshold.
Set IoU Threshold Using the YOLO CLI
For prediction:
yolo detect predict model=best.pt source=image.jpg iou=0.7
A stricter suppression configuration might be:
yolo detect predict model=best.pt source=image.jpg iou=0.4
You can also combine it with confidence:
yolo detect predict \
model=best.pt \
source=image.jpg \
conf=0.25 \
iou=0.7
The iou value is limited to the usual 0 to 1 range for NMS configuration.
Set IoU Threshold in Python
Using Python:
from ultralytics import YOLO
model = YOLO("best.pt")
results = model.predict(
source="image.jpg",
conf=0.25,
iou=0.7
)
Or simply:
results = model(
"image.jpg",
iou=0.7
)
This modifies NMS behavior during prediction.
Configure IoU for Prediction and Validation
Prediction example:
yolo detect predict model=best.pt source=test.jpg iou=0.7
Validation can also receive an iou setting as part of post-processing:
yolo detect val model=best.pt data=data.yaml iou=0.7
However, this validation iou argument should not be interpreted as replacing the IoU thresholds used to report standard mAP50-95.
The standard metric still evaluates AP over its defined IoU range.
Choosing the Best YOLOv8 IoU Threshold
There is no universal best IoU threshold for inference.
The correct value depends on:
- object density,
- degree of overlap,
- detector quality,
- number of duplicate predictions,
- deployment requirements.
A common approach is to start from the Ultralytics prediction default and then tune it using representative validation or deployment images. Current Ultralytics prediction documentation uses 0.7 as the standard inference NMS IoU default, while the underlying NMS utility itself documents 0.45 as its function-level default.
The higher-level prediction setting is the one most users should follow when using the normal YOLO API.
IoU for Crowded Scenes
Crowded scenes contain legitimate objects that overlap.
Examples include:
pedestrians in crowds
vehicles in traffic
animals in groups
products on shelves
A relatively higher NMS IoU may help prevent legitimate neighboring detections from suppressing one another.
For example:
iou=0.7
may retain more overlapping objects than:
iou=0.3
However, if the model itself generates many duplicate boxes, very high IoU can produce cluttered outputs.
IoU for Small and Overlapping Objects
Small objects can be challenging because even small coordinate differences can significantly change IoU.
If two nearby small targets overlap in the image, aggressive NMS can remove one of them.
In this situation, test higher values such as:
0.6
0.7
0.8
and inspect whether true neighboring detections are retained.
The best value should be selected from actual deployment examples rather than assumed from object size alone.
Balancing Duplicate and Missed Detections
The practical tradeoff is:
Lower IoU
→ fewer duplicate boxes
→ greater risk of suppressing neighboring objects
versus:
Higher IoU
→ more overlapping objects retained
→ greater risk of duplicate detections
The goal is to find a setting that removes redundant predictions without eliminating valid overlapping objects.
IoU Threshold vs Confidence Threshold
IoU and confidence control different stages of prediction filtering.
They are often adjusted together, but they should not be confused.
Main Difference Between IoU and Confidence
Confidence asks:
How certain is the model that this prediction is valid?
IoU asks:
How much do two boxes overlap?
The confidence threshold removes predictions based on model confidence.
The IoU threshold affects overlap-based suppression.
For example:
conf=0.25
means predictions below the selected confidence are filtered.
iou=0.7
controls how overlapping predictions are treated during NMS.
How Both Thresholds Work Together
A simplified inference pipeline is:
Raw Predictions
↓
Confidence Filtering
↓
Candidate Boxes
↓
IoU-Based NMS
↓
Final Detections
If confidence is too low, many weak candidate boxes reach NMS.
If IoU is too high, more overlapping candidates may remain.
Therefore, poor combinations can produce excessive boxes.
For example:
conf=0.05
iou=0.90
may allow many low-confidence and overlapping detections to survive compared with more conservative settings.
How IoU Threshold Affects YOLOv8 Performance
Changing the NMS IoU threshold does not retrain the model. It changes how predictions are filtered after the network generates them.
As a result, changing iou can change the final number of detections and influence apparent precision and recall at deployment.
Impact on Precision
A lower IoU threshold can reduce duplicate detections.
This may improve practical precision when many duplicates are counted as unnecessary predictions.
However, overly aggressive suppression can remove legitimate detections.
Therefore:
Lower IoU
≠ automatically higher precision
The actual result depends on the dataset.
Impact on Recall
In crowded scenes, an overly low NMS IoU threshold may suppress legitimate objects.
That can reduce recall.
For example:
Person A box overlaps Person B box
If NMS decides they are duplicates, one person may disappear from the final predictions.
Increasing the IoU threshold can sometimes preserve both.
Impact on Final Detection Results
Consider the same image with:
iou=0.3
and:
iou=0.8
At 0.3, the final output may contain fewer boxes.
At 0.8, more overlapping detections may remain.
The best output is not simply the one containing fewer or more boxes. It is the one that best represents the true objects without duplication.
Common YOLOv8 IoU Threshold Problems
Incorrect IoU configuration can produce recognizable prediction patterns.
Understanding these patterns makes threshold tuning much easier.
Duplicate Bounding Boxes
If one object repeatedly gets several boxes:
Object
├── Box 1
├── Box 2
└── Box 3
the NMS threshold may be too permissive.
Try lowering:
iou=0.8
to:
iou=0.6
or:
iou=0.5
and compare the output.
Also verify the confidence threshold, because many weak detections can increase duplicate-looking outputs.
Missing Overlapping Objects
If valid neighboring objects disappear, NMS may be too aggressive.
For example:
Two people
↓
Only one detection survives
Try increasing the IoU threshold.
This gives overlapping detections more tolerance before suppression.
Too Many False Positives
False positives are not always caused by IoU.
If the model detects background patterns as real objects, the underlying causes may include:
- low confidence threshold,
- poor training data,
- missing hard negatives,
- annotation errors,
- overfitting.
Changing IoU can modify duplicate behavior but will not automatically fix a model that fundamentally misclassifies background regions.
Incorrect Threshold Selection
A common mistake is assuming:
iou=0.5
means the same thing everywhere in YOLOv8.
It does not.
For example:
mAP50
uses IoU 0.50 as an evaluation criterion.
But:
predict iou=0.5
controls NMS behavior.
These are conceptually different settings.
Always identify whether you are changing:
prediction NMS
or:
evaluation matching criteria
before interpreting the number.
FAQs About YOLOv8 IoU Threshold
What is IoU threshold in YOLOv8?
The IoU threshold is a cutoff based on bounding-box overlap.
In normal Ultralytics prediction mode, the configurable:
iou
parameter controls the IoU threshold used for Non-Maximum Suppression.
If two boxes overlap beyond the configured amount, NMS may suppress the lower-confidence box.
What is a good IoU threshold for YOLOv8?
There is no universal best value.
Current Ultralytics prediction mode uses:
iou=0.7
as its default NMS IoU threshold.
Use that as a baseline and test lower or higher values based on:
- duplicate detections,
- crowded scenes,
- overlapping objects,
- precision and recall requirements.
What happens if the IoU threshold is too high?
A high NMS IoU threshold allows more overlapping boxes to remain.
Possible effects include:
more duplicate detections
more boxes around one object
better retention of overlapping objects
If duplicate boxes become common, reduce the value.
What happens if the IoU threshold is too low?
A low NMS threshold suppresses boxes more aggressively.
Possible effects include:
fewer duplicates
cleaner outputs
legitimate neighboring objects removed
lower recall in crowded scenes
If real overlapping objects are being lost, increase the threshold.
What is the difference between IoU threshold and confidence threshold?
Confidence controls whether an individual prediction is strong enough to keep.
IoU controls how overlapping boxes are handled.
Conceptually:
Confidence
→ Is this detection believable?
IoU
→ Are these boxes too similar?
Both settings affect the final prediction output but solve different filtering problems.
Does IoU threshold affect precision and recall?
It can.
A lower NMS IoU threshold can reduce duplicate predictions but may suppress valid nearby objects.
A higher threshold can retain overlapping objects but may leave duplicates.
Therefore, changing IoU can indirectly affect practical precision and recall through post-processing.
Can I change the IoU threshold during YOLOv8 inference?
Yes.
CLI:
yolo detect predict model=best.pt source=image.jpg iou=0.6
Python:
results = model.predict(
source="image.jpg",
iou=0.6
)
Ultralytics officially exposes iou as an inference setting for NMS filtering.
Conclusion
The YOLOv8 IoU threshold controls how bounding-box overlap is interpreted, but its meaning depends on where it is used.
During prediction, the configurable:
iou
parameter is mainly the threshold used for Non-Maximum Suppression.
The inference process can be summarized as:
YOLO Predictions
↓
Confidence Filtering
↓
Calculate Box Overlap
↓
Apply IoU-Based NMS
↓
Remove Redundant Boxes
↓
Final Detections
Current Ultralytics prediction mode uses iou=0.7 as the normal high-level prediction default, while the lower-level NMS utility documents 0.45 as its function default. Users working through the standard YOLO.predict() or CLI workflow should generally follow the prediction-mode setting.
The effect of NMS IoU can be summarized as:
Lower IoU Threshold
→ more aggressive suppression
→ fewer duplicate boxes
→ greater risk of removing overlapping objects
and:
Higher IoU Threshold
→ less aggressive suppression
→ better retention of crowded objects
→ greater risk of duplicate detections
Validation uses IoU differently. Metrics such as:
mAP50
evaluate AP at IoU 0.50, while:
mAP50-95
averages AP across thresholds from 0.50 to 0.95. These evaluation thresholds are not the same thing as the user-configurable NMS iou argument.
A practical tuning workflow is:
Start with Default IoU
↓
Inspect Duplicate Boxes
↓
Inspect Overlapping Objects
↓
Lower IoU if Duplicates Are Excessive
↓
Raise IoU if Valid Objects Are Suppressed
↓
Compare Precision and Recall
↓
Test on Real Deployment Images
The right IoU threshold should therefore be selected experimentally. Use representative images, compare duplicate detections and missed overlapping objects, and evaluate the result together with confidence threshold, precision, recall, and mAP rather than treating one IoU value as universally optimal.
I’m Jane Austen, a skilled content writer with the ability to simplify any complex topic. I focus on delivering valuable tips and strategies throughout my articles.