yolo-datasets · diff
git:20260811.e35dbcc to git:20260814.05a799c
20 added, 12 removed. Audit A to A.
---
name: yolo-datasets
description: >
Use when uploading, annotating, building, converting, analyzing, or debugging datasets
in Ultralytics Platform or local YOLO — Platform dataset management and Smart
Annotation, data.yaml, YOLO label .txt formats, COCO/DOTA/mask conversion,
auto-labeling, splits, validation, and errors like "no labels found" or mAP near 0.
Covers detect, segment, semantic, depth, classify, pose, and OBB data.
---
# Ultralytics YOLO datasets
The #1 cause of silent training failure is a malformed dataset — validate before training.
## Fastest route: prepare data in Platform
1. Open [Platform](https://platform.ultralytics.com), create a dataset under
**Annotate**, and choose its task.
2. Upload images, videos, ZIP/TAR archives, or NDJSON. Existing YOLO labels and COCO JSON
can be imported; cloud-storage integrations can keep supported data in place.
3. Open an image in the fullscreen editor. Use manual tools for detect, segment,
semantic, classify, pose, or OBB. For detect, segment, semantic, and OBB, switch to
**Smart** mode to label with SAM or predictions from a compatible official/custom YOLO
model.
4. Review the **Classes**, **Charts**, and **Errors** tabs, fix the split, and create a
numbered dataset version before important runs.
Platform datasets currently cover six tasks; depth dataset support is still pending.
Smart Annotation is unavailable for connected cloud datasets. See
[Platform Data](https://docs.ultralytics.com/platform/data/) and the
[Annotation Editor](https://docs.ultralytics.com/platform/data/annotation/).
To train on the same dataset from local code, create an API key under **Settings > API
Keys**, set `ULTRALYTICS_API_KEY`, and use its URI directly:
```bash
yolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug epochs=100
```
Export NDJSON when you need a portable snapshot instead of live Platform access.
## The `images` → `labels` mirror rule
Ultralytics finds a label file by replacing the **last** `/images/` path segment with
`/labels/` and the image extension with `.txt`:
```
dataset/
├── data.yaml
├── images/train/ img001.jpg ... ├── images/val/ ...
└── labels/train/ img001.txt ... └── labels/val/ ...
```
- Labels next to images, or in a dir not named `labels`, are **not found** → silent
all-background training.
- Filenames must match stems exactly (case-sensitive on Linux).
- An image with no/empty label file trains as a **background image**. A few percent of
true backgrounds reduce false positives; accidentally missing labels destroy recall.
## data.yaml anatomy
```yaml
path: /abs/dataset/root # relative paths resolve against `yolo settings` datasets_dir — prefer absolute
train: images/train # dir, .txt file of image paths, or list of dirs
val: images/val
test: images/test # optional
names: # 0-based, contiguous indices
0: person
1: helmet
# pose only:
kpt_shape: [17, 3] # [num_keypoints, dims]; dims 2 (x,y) or 3 (x,y,visibility)
flip_idx: [0, 2, 1, ...] # L/R keypoint swap map — without it, flip augs are auto-disabled
# semantic only (optional — polygon labels/ also work):
masks_dir: masks # per-pixel PNG mask images
# depth only: paired depth/{train,val}/*.npy float32 depth maps, nc: 1
```
- Classification datasets use **no yaml**: folder structure is the label
(`dataset/train/<class>/*.jpg`, `dataset/val/<class>/*.jpg`); train with
`data=path/to/dataset`.
- Per-task label line formats and their gotchas: read `label-formats.md` (this folder)
whenever writing or debugging label files.
## Converting from other formats — use built-ins first
```python
from ultralytics.data.converter import convert_coco
convert_coco(labels_dir="coco/annotations/", use_segments=True) # COCO → detect/segment
convert_coco(labels_dir="coco/annotations/", use_keypoints=True) # COCO → pose
```
Also in `ultralytics.data.converter`: `convert_dota_to_yolo_obb(root)` (DOTA → OBB),
`convert_segment_masks_to_yolo_seg(masks_dir, output_dir, classes)` (index PNGs →
polygons), `yolo_bbox2segment(im_dir)` (upgrade detect labels to segment via SAM),
`convert_to_multispectral(path, n_channels)`.
Auto-label a raw image folder (detector proposes boxes, SAM refines masks):
```python
from ultralytics.data.annotator import auto_annotate
auto_annotate(data="path/to/images", det_model="yolo26x.pt", sam_model="sam_b.pt")
```
For VOC XML/CSV there is no converter — write a small script emitting the per-task line
format (normalize coords, center-based boxes).
## Splitting
```python
from ultralytics.data.split import autosplit
autosplit(path="dataset/images", weights=(0.9, 0.1, 0.0)) # writes autosplit_*.txt lists
```
Point `train:`/`val:` at the generated `.txt` files. Keep frames from the same
video/scene in ONE split — per-image random splits of video frames leak near-duplicates
into val and inflate mAP. For classify: `split_classify_dataset(source_dir, 0.8)`.
- ## Validate before training (do this, in order)
+ ## Validate before training (use the task-relevant steps in order)
- 1. **Structural check** — loads, resolves paths, counts images/labels, auto-downloads
- known datasets:
+ 1. **YAML/path check (non-classification)** — validates required fields, resolves
+ configured paths, checks the requested split (default `val`), and may auto-download a
+ known dataset. It does not count or parse individual images and targets:
```python
from ultralytics.data.utils import check_det_dataset
check_det_dataset("data.yaml") # detect/segment/pose/obb/semantic/depth
```
- 2. **Visual check of one image** — labels drawn on the image; wrong normalization or
- swapped x/y is instantly visible:
+ 2. **Detection-only visual spot check** — this helper accepts five-column
+ `class cx cy w h` rows; wrong normalization or swapped axes become visible:
```python
from ultralytics.data.utils import visualize_image_annotations
- visualize_image_annotations("images/train/img001.jpg", "labels/train/img001.txt", label_map={0: "person", 1: "helmet"})
+ visualize_image_annotations(
+ "images/train/img001.jpg",
+ "labels/train/img001.txt",
+ label_map={0: "person", 1: "helmet"},
+ )
```
- 3. **1-epoch smoke test**, then eyeball the mosaic:
+ Do not use this helper for segment, pose, OBB, semantic, depth, or classify targets;
+ use their task-aware trainer plots instead.
+
+ 3. **Task-loader smoke test** — run one epoch with matching task/model/data; this builds
+ the real dataset and produces task-aware training plots (detection example):
```bash
yolo detect train data=data.yaml model=yolo26n.pt epochs=1 fraction=0.1
- # inspect runs/detect/train/train_batch0.jpg — boxes/masks must sit on objects
+ # inspect runs/detect/train/train_batch0.jpg — boxes must sit on objects
```
- 4. **Distribution sanity** (quick script over label files): instances per class
- (heavy imbalance → collect more or weigh expectations), boxes < ~8 px at train
- `imgsz` (undetectable — raise imgsz or tile), % background images, duplicate
- stems across splits (leakage).
+ 4. **Distribution sanity** — check task-appropriate class/target balance and split
+ leakage. For box tasks, also inspect very small boxes at train `imgsz` and the
+ background-image share.
Known-good tiny datasets for pipeline smoke tests (auto-download): `coco8.yaml`,
`coco8-seg.yaml`, `coco8-pose.yaml`, `dota8.yaml`, `cityscapes8.yaml`, `depth8.yaml`,
`imagenet10`.
## Related pages
- `label-formats.md` — exact per-task label line formats + symptom→cause table. Read
when writing labels, converting formats, or any label-related error.
If the installed version rejects an argument or format here, trust its error message and
`yolo checks` over this file.