The YOLOv8 data YAML file tells Ultralytics where a dataset is located and how its classes are organized. A typical data.yaml file contains the dataset root, training and validation image paths, optional test data, and a mapping between class IDs and class names. Pose datasets can include additional fields such as kpt_shape and flip_idx. The YAML file acts as the connection between your dataset files and the YOLOv8 training process.
Introduction to the YOLOv8 Data YAML File
When training YOLOv8 on a custom dataset, the model needs to know where the training images are stored, where validation images can be found, and what each numerical class ID represents.
This information is provided through a dataset configuration file commonly called:
data.yaml
The YAML file does not normally contain the actual image annotations. Instead, it describes the dataset so Ultralytics can locate the images and corresponding labels.
For detection, segmentation, and OBB datasets, the basic configuration is very similar. Pose datasets use the same core structure but add keypoint-related settings.
What Is a Data YAML File in YOLOv8?
A data YAML file in YOLOv8 is a configuration file containing dataset-specific information required by the training and validation pipeline.
A basic file might look like:
path: /datasets/my_dataset
train: images/train
val: images/val
names:
0: person
1: car
2: bicycle
This tells YOLO that:
- the dataset root is
/datasets/my_dataset, - training images are under
images/train, - validation images are under
images/val, - three object classes are available.
Ultralytics describes its YOLO dataset configuration format as containing a dataset root, train/validation/test paths, and a class-name dictionary.
Role of the YAML File During Training
The YAML file serves as a map between YOLO and your custom dataset.
When you run:
yolo detect train model=yolov8n.pt data=data.yaml epochs=100
Ultralytics reads data.yaml to determine where the dataset is located.
It then uses the configured image paths and automatically finds the corresponding labels according to the YOLO dataset structure.
Without the correct dataset configuration, the training process may not know:
- where training images are,
- where validation images are,
- how many classes exist,
- what numerical class IDs represent.
The data training argument points directly to this dataset configuration file.
Why YOLOv8 Needs Dataset Configuration
Different projects can store data in different locations and use completely different classes.
One project may detect:
person
car
truck
while another may detect:
crack
scratch
dent
The YAML file allows the same YOLO training code to work with either dataset without changing the model architecture manually.
Instead of hard-coding dataset details inside training code, they are kept in a separate readable configuration file.
YOLOv8 Data YAML File Structure
The most important fields in a typical YOLO dataset YAML are:
path:
train:
val:
test:
names:
Not every field is mandatory in every situation. For example, test is optional when you do not have a separate test split.
Train and Validation Paths
The train field tells YOLO where the training images are stored.
The val field defines validation data.
For example:
path: /datasets/vehicles
train: images/train
val: images/val
Ultralytics combines the root path with the relative split paths.
This produces:
/datasets/vehicles/images/train
/datasets/vehicles/images/val
Train and validation fields can also point to supported text files containing image paths rather than only directories.
Number of Classes and Class Names
Classes are usually defined using the names mapping:
names:
0: person
1: car
2: motorcycle
The class indices are zero-based:
0 → person
1 → car
2 → motorcycle
In modern Ultralytics dataset files, the number of classes can be derived from the names mapping, so manually adding an nc field is generally unnecessary for a normal custom dataset.
You may still encounter older YOLO examples containing:
nc: 3
but keeping a correct names mapping is the essential part of current Ultralytics dataset configuration. The official detection dataset format centers on paths plus the class-name dictionary.
Optional Test Dataset Path
If you maintain an independent test split, you can add:
test: images/test
A complete split configuration might therefore be:
path: /datasets/vehicles
train: images/train
val: images/val
test: images/test
names:
0: car
1: truck
The test set is normally used for final evaluation rather than model weight optimization.
Ultralytics’ dataset format explicitly supports training, validation, and optional testing image paths.
YOLOv8 Data YAML File Example
A YAML file is simple text, but spacing and path configuration must be correct.
Basic YAML Configuration
A basic single-class dataset can use:
path: /datasets/custom
train: images/train
val: images/val
names:
0: object
The corresponding folder structure could be:
custom/
├── images/
│ ├── train/
│ └── val/
├── labels/
│ ├── train/
│ └── val/
└── data.yaml
Example for a Custom Dataset
Suppose you want to train YOLOv8 to detect helmets, workers, and safety vests.
Your YAML file could be:
path: /home/user/safety_dataset
train: images/train
val: images/val
test: images/test
names:
0: helmet
1: worker
2: safety_vest
A label containing:
2 0.51 0.44 0.30 0.42
would use class ID 2, meaning:
safety_vest
The YAML and annotation class IDs must therefore remain synchronized.
Relative vs Absolute Dataset Paths
Both absolute and relative paths can be used in a practical dataset configuration.
An absolute dataset root may look like:
path: /home/user/datasets/cars
On Windows:
path: C:/datasets/cars
You can then use relative split paths:
train: images/train
val: images/val
This approach is usually easier to maintain than writing full absolute paths for every split.
A project-relative setup can also be used when your dataset structure and execution environment make those paths unambiguous.
How to Create a YOLOv8 Data YAML File
You can create data.yaml using any plain-text editor.
Define Dataset Folder Locations
First decide where the dataset root is located.
For example:
my_dataset/
├── images/
│ ├── train/
│ └── val/
├── labels/
│ ├── train/
│ └── val/
└── data.yaml
Then define:
path: /path/to/my_dataset
train: images/train
val: images/val
Make sure the paths actually exist.
Add Class Names Correctly
Next, list every class in numerical order:
names:
0: person
1: bicycle
2: car
If your annotation contains class:
0
YOLO interprets it as:
person
Class:
2
becomes:
car
Do not change the YAML class ordering after labels have already been created unless the label IDs are also updated.
Save and Validate the YAML File
Save the file with a .yaml extension:
data.yaml
Before training, check:
- dataset root,
- train path,
- validation path,
- optional test path,
- class names,
- class ordering,
- indentation.
A quick training run with a small model can also help identify configuration errors before launching a large experiment.
Ultralytics provides tiny datasets such as COCO8 specifically for testing and debugging training pipelines.
Using the Data YAML File for YOLOv8 Training
Once created, the YAML file is passed to the data training argument.
Load the YAML File with the CLI
For detection:
yolo detect train model=yolov8n.pt data=data.yaml epochs=100 imgsz=640
If the YAML is stored elsewhere:
yolo detect train model=yolov8n.pt data=/path/to/data.yaml epochs=100 imgsz=640
Ultralytics’ training interface uses the data parameter for the dataset configuration file.
Use the YAML File in Python
Using Python:
from ultralytics import YOLO
model = YOLO("yolov8n.pt")
model.train(
data="data.yaml",
epochs=100,
imgsz=640
)
The same dataset YAML can therefore be used from either the CLI or Python API.
Connect the YAML File to a Custom Dataset
Suppose your dataset is stored at:
D:/datasets/vehicles/
with:
D:/datasets/vehicles/images/train
D:/datasets/vehicles/images/val
D:/datasets/vehicles/labels/train
D:/datasets/vehicles/labels/val
Your YAML could be:
path: D:/datasets/vehicles
train: images/train
val: images/val
names:
0: car
1: truck
2: bus
You can then train with:
yolo detect train model=yolov8n.pt data=D:/datasets/vehicles/data.yaml epochs=100
Data YAML Files for Different YOLOv8 Tasks
Detection, segmentation, pose, and OBB all use dataset configuration files, but some tasks require additional fields or different annotation formats.
Detection Dataset YAML
A detection YAML might be:
path: /datasets/detection
train: images/train
val: images/val
names:
0: person
1: vehicle
The corresponding labels use standard detection boxes:
class x_center y_center width height
The official Ultralytics detection dataset format uses the YAML to define the dataset root, split paths, and class names.
Segmentation Dataset YAML
An instance segmentation YAML can use essentially the same core dataset configuration:
path: /datasets/segmentation
train: images/train
val: images/val
names:
0: person
1: car
The difference is mainly in the annotation files.
Segmentation labels contain polygon coordinates rather than standard bounding boxes.
Therefore, the YAML identifies dataset paths and classes, while the label format determines that the data represents segmentation instances. Official Ultralytics segmentation datasets likewise maintain YAML files containing paths and class information.
Pose Dataset YAML
Pose datasets require additional information describing the keypoints.
For example:
path: /datasets/custom_pose
train: images/train
val: images/val
names:
0: person
kpt_shape: [17, 3]
flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]
kpt_shape defines:
[number_of_keypoints, values_per_keypoint]
For:
kpt_shape: [17, 3]
there are 17 keypoints with three values per point.
The flip_idx field defines how keypoint indices should be exchanged during horizontal-flip augmentation.
Ultralytics’ pose dataset configuration specifically includes kpt_shape and supports keypoint-related configuration in addition to normal paths and class information.
OBB Dataset YAML
An oriented bounding box dataset uses the same basic YAML structure:
path: /datasets/custom_obb
train: images/train
val: images/val
names:
0: plane
1: ship
2: vehicle
The difference is in the labels, which represent each OBB using four corner points.
Ultralytics’ OBB dataset documentation confirms that OBB datasets use a YAML configuration containing dataset paths, classes, and related metadata.
Common YOLOv8 Data YAML Errors
Many training errors come from incorrect paths or mismatches between annotations and class definitions.
Incorrect Dataset Paths
Suppose your YAML contains:
path: /datasets/cars
train: images/train
but the actual data is located at:
/datasets/car_dataset/images/train
YOLO will not find the expected images.
Check the resolved path carefully.
On Windows, forward slashes can make paths easier to read:
path: C:/Users/Name/datasets/cars
Missing Class Names
A dataset configuration needs a correct class mapping.
For example:
names:
0: car
1: truck
Do not leave the names inconsistent with your annotation IDs.
If labels refer to object classes but the dataset configuration cannot map those classes correctly, training cannot interpret the annotations as intended.
Class Count Mismatch
Suppose your YAML contains:
names:
0: person
1: car
but a label contains:
2 0.5 0.5 0.2 0.3
The label references a third class that is not defined.
The highest class ID used in annotations must fit within the class-name mapping.
Similarly, if you define:
names:
0: person
1: car
2: bus
ensure the corresponding annotation IDs follow exactly the same ordering.
YAML Syntax and Indentation Errors
YAML depends on correct indentation.
Correct:
names:
0: person
1: car
Incorrect formatting such as inconsistent indentation can cause parsing errors.
Also avoid tabs when possible; use spaces consistently.
Another common error is forgetting the colon:
train images/train
instead of:
train: images/train
Best Practices for YOLOv8 Data YAML Files
A clean dataset configuration reduces path errors and makes training easier to reproduce.
Keep Dataset Paths Consistent
A useful structure is:
project/
└── dataset/
├── images/
│ ├── train/
│ └── val/
├── labels/
│ ├── train/
│ └── val/
└── data.yaml
Then configure one root:
path: /path/to/project/dataset
with relative split paths.
This avoids unnecessarily repeating long paths.
Match Labels with Class Names
Before training, check several labels manually.
If your YAML says:
names:
0: cat
1: dog
then every annotation with class 0 must actually represent a cat.
A class ordering mistake can result in a model that appears to train normally but learns incorrect class identities.
Check the YAML File Before Training
Before a long experiment, verify:
✓ path exists
✓ train directory exists
✓ val directory exists
✓ label directories exist
✓ class IDs are valid
✓ names are correctly ordered
✓ YAML indentation is valid
✓ task-specific settings are present
For pose datasets, additionally verify kpt_shape and any flip mapping.
For OBB and segmentation, verify that the labels follow the correct task-specific annotation format rather than standard detection labels.
FAQs About YOLOv8 Data YAML Files
What is a data YAML file in YOLOv8?
A data YAML file is a dataset configuration file that tells Ultralytics where training, validation, and optionally test data are located and defines the dataset’s class names. Pose YAML files can also include keypoint configuration.
What should a YOLOv8 YAML file contain?
A typical custom detection YAML contains:
path: /path/to/dataset
train: images/train
val: images/val
names:
0: class_one
1: class_two
You can optionally add:
test: images/test
Task-specific configurations may contain additional fields.
How do I create a custom data.yaml file?
Create a plain-text file ending in .yaml, define your dataset root, train and validation image paths, and add the class-name mapping.
For example:
path: C:/datasets/animals
train: images/train
val: images/val
names:
0: cat
1: dog
Then pass the file to YOLO using:
data=data.yaml
Can I use absolute paths in YOLOv8 data YAML?
Yes. An absolute root path can be used, for example:
path: /home/user/datasets/cars
or:
path: C:/datasets/cars
You can then keep train, val, and test relative to that root.
What does names mean in the YOLOv8 YAML file?
names maps numerical class IDs to readable object names.
For example:
names:
0: person
1: car
2: truck
means class ID 0 is person, 1 is car, and 2 is truck. The class-name dictionary is one of the core fields in the Ultralytics YOLO dataset format.
Why is YOLOv8 not finding my dataset?
Common causes include:
- incorrect
path, - incorrect
trainorvalpath, - wrong folder names,
- missing images,
- incorrect YAML indentation,
- running with the wrong YAML file,
- image and label directories not following the expected dataset layout.
Start by manually resolving the path.
If the YAML contains:
path: C:/datasets/cars
train: images/train
verify that this directory actually exists:
C:/datasets/cars/images/train
Can the same YAML file be used for detection and segmentation?
The core YAML structure can be very similar, because both tasks require dataset paths and class names.
For example, both may contain:
path:
train:
val:
names:
However, the underlying annotation files are different. Detection uses bounding-box labels, while instance segmentation uses polygon labels.
Therefore, you should not point detection and segmentation training at the same labels unless the dataset actually contains the annotation format required by that task. Pose datasets additionally require keypoint-related configuration such as kpt_shape.
Conclusion
The YOLOv8 data YAML file is the main configuration that connects a custom dataset to the Ultralytics training pipeline. It defines where the data is stored and maps numerical annotation IDs to readable class names.
A standard configuration looks like:
path: /datasets/custom
train: images/train
val: images/val
test: images/test
names:
0: person
1: car
Detection, segmentation, and OBB datasets use this same core idea, while their underlying annotation formats differ. Pose datasets extend the YAML with keypoint-related fields such as kpt_shape and flip_idx.
Before training, verify paths, class IDs, YAML syntax, and task-specific settings. A correctly configured data.yaml prevents many common dataset-loading errors and makes YOLOv8 custom training easier to reproduce.
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.