---
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)

1. **Structural check** — loads, resolves paths, counts images/labels, auto-downloads
   known datasets:

   ```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:

   ```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"})
   ```

3. **1-epoch smoke test**, then eyeball the mosaic:
   ```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
   ```
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).

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.