Prepare a Custom Dataset

Get the Practice Dataset#

The layout below is also what Ultralytics Platform's New Dataset dialog accepts as a zip, so a dataset you prepare here uploads unchanged. Download 92 training and 23 validation frames of pills in blister packs, and unpack them into my_dataset:

curl -L -o medical-pills.zip https://github.com/ultralytics/assets/releases/download/v0.0.0/medical-pills.zip
unzip -q medical-pills.zip -d my_dataset

my_dataset/
├── images/
│   ├── train/   Frame_0.jpg, Frame_100.jpg, ... (92 images)
│   └── val/     Frame_144.jpg, ... (23 images)
└── labels/
    ├── train/   Frame_0.txt, Frame_100.txt, ... (92 files)
    └── val/     Frame_144.txt, ... (23 files)

There's no manifest. Ultralytics finds each label by replacing /images/ with /labels/ in the image path and the extension with .txt, so images/val/Frame_144.jpg reads labels/val/Frame_144.txt. Two consequences:

• The folders must be named exactly images and labels, side by side.
• An image with an empty or missing label file is a background image: valid, and useful for teaching the model what not to detect, but only when you meant it.

Read a Label Line#

Each line is one object: an integer class index, then the bounding box center and size as fractions of the image width and height. A real line from labels/train/Frame_0.txt:

0 0.330729 0.816204 0.103125 0.121296

• 0: class index 0, which the YAML will name pill.
• 0.330729 0.816204: the box center sits 33% of the way across and 82% of the way down.
• 0.103125 0.121296: the box is about 10% of the image wide and 12% tall.

Worked Example: Convert a Pixel Box#

Labeling tools often export corners in pixels (x1, y1, x2, y2). Divide by the image size. The leftmost person in the 810×1080 bus.jpg from the last lesson spans (49, 398) to (240, 902):

Most labeling tools, and tools like Roboflow, can export YOLO format directly. For COCO JSON, follow the COCO JSON training guide; the JSON2YOLO repository covers other formats. For Pascal VOC XML, the formula above fits in a short script:

import xml.etree.ElementTree as ET
from pathlib import Path

CLASSES = ["person", "bus"]  # index = class id; must match names in data.yaml

def voc_to_yolo(xml_file: Path, out_dir: Path) -> None:
    root = ET.parse(xml_file).getroot()
    w, h = int(root.find("size/width").text), int(root.find("size/height").text)
    lines = []
    for obj in root.iter("object"):
        name = obj.find("name").text
        if name not in CLASSES:
            continue
        box = obj.find("bndbox")
        x1, y1, x2, y2 = (float(box.find(k).text) for k in ("xmin", "ymin", "xmax", "ymax"))
        xc, yc, bw, bh = (x1 + x2) / 2 / w, (y1 + y2) / 2 / h, (x2 - x1) / w, (y2 - y1) / h
        lines.append(f"{CLASSES.index(name)} {xc:.6f} {yc:.6f} {bw:.6f} {bh:.6f}")
    out_dir.mkdir(parents=True, exist_ok=True)
    (out_dir / f"{xml_file.stem}.txt").write_text("\n".join(lines) + "\n")

voc_to_yolo(Path("bus.xml"), Path("labels"))
print(Path("labels/bus.txt").read_text())

Run on a bus.xml holding the person and bus boxes from the previous lesson, it prints the worked example and the bus:

0 0.178395 0.601852 0.235802 0.466667
1 0.495679 0.454167 0.991358 0.482407

Check Before You Train#

Draw a few label files on their images. A shifted class, swapped x and y, or boxes around shadows are obvious to the eye and invisible in metrics:

from ultralytics.data.utils import visualize_image_annotations

visualize_image_annotations(
    "my_dataset/images/train/Frame_0.jpg",
    "my_dataset/labels/train/Frame_0.txt",
    {0: "pill"},
)

Then let Ultralytics check every file. It scans labels the first time it reads a dataset and decides, line by line, whether each image is usable:

The scan line reports the result: 23 images, 0 backgrounds, 0 corrupt is what a healthy dataset looks like. Anything else is one of the mistakes below.

Avoid These Mistakes#

For systematic checks across a whole dataset, see Dataset Quality Control. Built-in sets such as coco8, coco128, and african-wildlife are good layouts to copy; the datasets overview lists them all. The trainer adds data augmentation on top of your labels, so a quick pass of data cleaning here pays off in every epoch.