docs/en/tasks/semantic.md
Semantic segmentation assigns a class label to every pixel in an image, producing a dense class map that covers the entire scene. Unlike instance segmentation, which separates individual objects, semantic segmentation groups all pixels of the same class together regardless of how many distinct objects are present.
The output of a semantic segmentation model is a single height-by-width class map where each pixel value corresponds to a predicted class ID. This makes semantic segmentation ideal for scene parsing tasks such as autonomous driving, medical imaging, and land-cover mapping.
!!! tip
Use `task=semantic` or the `yolo semantic` CLI task for semantic segmentation. YOLO26 semantic segmentation model files use the `-sem` suffix, such as `yolo26n-sem.pt`.
YOLO26 semantic segmentation models pretrained on the Cityscapes dataset are shown below.
Models download automatically from the latest Ultralytics release on first use.
{% include "macros/yolo-semantic-perf.md" %}
yolo semantic val data=cityscapes.yaml device=0 imgsz=2048yolo semantic val data=cityscapes.yaml batch=1 device=0|cpu imgsz=2048model.fuse(), which merges Conv and BatchNorm layers. Pretrained checkpoints retain the full training architecture and may show higher counts.Train YOLO26n-sem on the Cityscapes8 dataset for 100 epochs at image size 1024. For a full list of available arguments see the Configuration page.
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n-sem.yaml") # build a new model from YAML
model = YOLO("yolo26n-sem.pt") # load a pretrained model (recommended for training)
model = YOLO("yolo26n-sem.yaml").load("yolo26n-sem.pt") # build from YAML and transfer weights
# Train the model
results = model.train(data="cityscapes8.yaml", epochs=100, imgsz=1024)
```
=== "CLI"
```bash
# Build a new model from YAML and start training from scratch
yolo semantic train data=cityscapes8.yaml model=yolo26n-sem.yaml epochs=100 imgsz=1024
# Start training from a pretrained *.pt model
yolo semantic train data=cityscapes8.yaml model=yolo26n-sem.pt epochs=100 imgsz=1024
# Build a new model from YAML, transfer pretrained weights to it and start training
yolo semantic train data=cityscapes8.yaml model=yolo26n-sem.yaml pretrained=yolo26n-sem.pt epochs=100 imgsz=1024
```
See full train mode details in the Train page.
Semantic segmentation datasets use single-channel mask images, typically PNG, where each pixel value represents a class ID. Pixels with value 255 are treated as "ignore" and excluded from loss computation. The dataset YAML should specify paths to images and their corresponding mask directories. See the Semantic Segmentation Dataset Guide for format details. Supported datasets include Cityscapes and ADE20K.
Validate trained YOLO26n-sem model accuracy on a semantic segmentation dataset. Pass data explicitly so validation uses the intended dataset YAML.
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n-sem.pt") # load an official model
model = YOLO("path/to/best.pt") # load a custom model
# Validate the model
metrics = model.val(data="cityscapes.yaml")
metrics.miou # mean Intersection over Union
metrics.pixel_accuracy # overall pixel accuracy
```
=== "CLI"
```bash
yolo semantic val model=yolo26n-sem.pt data=cityscapes.yaml # validate official model
yolo semantic val model=path/to/best.pt data=path/to/data.yaml # validate custom model
```
Use a trained YOLO26n-sem model to run predictions on images.
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n-sem.pt") # load an official model
model = YOLO("path/to/best.pt") # load a custom model
# Predict with the model
results = model("https://ultralytics.com/images/bus.jpg") # predict on an image
# Access the results
for result in results:
semantic_mask = result.semantic_mask.data # height x width class map (torch.Tensor)
```
=== "CLI"
```bash
yolo semantic predict model=yolo26n-sem.pt source='https://ultralytics.com/images/bus.jpg' # predict with official model
yolo semantic predict model=path/to/best.pt source='https://ultralytics.com/images/bus.jpg' # predict with custom model
```
See full predict mode details in the Predict page.
Export a YOLO26n-sem model to a different format like ONNX, CoreML, etc.
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n-sem.pt") # load an official model
model = YOLO("path/to/best.pt") # load a custom model
# Export the model
model.export(format="onnx")
```
=== "CLI"
```bash
yolo export model=yolo26n-sem.pt format=onnx # export official model
yolo export model=path/to/best.pt format=onnx # export custom model
```
Available YOLO26 semantic segmentation export formats are in the table below. You can export to any format using the format argument, i.e., format='onnx' or format='engine'. You can predict or validate directly on exported models, i.e., yolo predict model=yolo26n-sem.onnx. Usage examples are shown for your model after export completes.
{% include "macros/export-table.md" %}
See full export details in the Export page.
To train a YOLO26 semantic segmentation model on a custom dataset, you need to prepare PNG mask images where each pixel value represents a class ID (0, 1, 2, ...) and pixels with value 255 are ignored during training. Create a dataset YAML file pointing to your images and masks directories, then train the model:
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a pretrained YOLO26 semantic segmentation model
model = YOLO("yolo26n-sem.pt")
# Train the model
results = model.train(data="path/to/your_dataset.yaml", epochs=100, imgsz=512)
```
=== "CLI"
```bash
yolo semantic train data=path/to/your_dataset.yaml model=yolo26n-sem.pt epochs=100 imgsz=512
```
Check the Configuration page for more available arguments.
Instance segmentation and semantic segmentation are both pixel-level tasks but differ in a key way:
Semantic segmentation is best suited for scene understanding tasks like autonomous driving and land-cover mapping, while instance segmentation is preferred when counting or tracking individual objects matters.
Yes. If your dataset uses Ultralytics YOLO polygon labels (one .txt per image), omit masks_dir from the dataset YAML and the loader will convert polygons to per-image semantic masks on the fly. For multi-class datasets (N > 1) an extra background class is appended to names automatically. For single-class datasets (N == 1) training stays at 1 class — your declared class becomes 1 in the mask and uncovered pixels become 0. See the Semantic Segmentation Dataset Guide for details.
Ultralytics YOLO26 provides built-in configurations for several semantic segmentation datasets:
You can also use any custom dataset that provides PNG mask annotations where pixel values correspond to class IDs.
Validate a pretrained YOLO26 semantic segmentation model with the dataset YAML used for evaluation:
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a pretrained model
model = YOLO("yolo26n-sem.pt")
# Validate the model
metrics = model.val(data="cityscapes.yaml")
print("Mean IoU:", metrics.miou)
print("Pixel Accuracy:", metrics.pixel_accuracy)
```
=== "CLI"
```bash
yolo semantic val model=yolo26n-sem.pt data=cityscapes.yaml
```
These steps will provide you with validation metrics like mean Intersection over Union (mIoU) and pixel accuracy, which are standard measures for assessing semantic segmentation performance.
Export a YOLO26 semantic segmentation model to ONNX format with Python or CLI commands:
!!! example
=== "Python"
```python
from ultralytics import YOLO
# Load a pretrained model
model = YOLO("yolo26n-sem.pt")
# Export the model to ONNX format
model.export(format="onnx")
```
=== "CLI"
```bash
yolo export model=yolo26n-sem.pt format=onnx
```
For more details on exporting to various formats, refer to the Export page.