The YOLOv8 Pose dataset format extends the standard YOLO object detection format by adding keypoint coordinates to each labeled object. Every training image has a corresponding text label file containing the class ID, normalized bounding box coordinates, and the defined keypoints. Depending on the dataset configuration, each keypoint can contain either x, y coordinates or x, y, visibility values. A correctly structured dataset and YAML configuration are essential for successfully training YOLOv8 Pose on custom landmarks.
Introduction to YOLOv8 Pose Dataset Format
YOLOv8 Pose requires more detailed annotations than normal object detection because the model must learn both where an object is located and where its important landmarks are positioned.
For a human pose dataset, these landmarks might include shoulders, elbows, wrists, hips, knees, and ankles. For a custom pose project, they could represent animal joints, hand landmarks, machine components, or any other meaningful points.
Ultralytics uses a YOLO-style text format in which each image has a corresponding label file. Each annotation row describes one object instance and includes its bounding box followed by its keypoints.
What Is the YOLOv8 Pose Dataset Format?
The YOLOv8 Pose dataset format is an annotation structure designed for training YOLO models to perform both object localization and keypoint estimation.
A pose label begins with the same basic information used by object detection:
class_id x_center y_center width height
It then adds the keypoint values:
kp1_x kp1_y kp1_v kp2_x kp2_y kp2_v ...
For datasets configured without a visibility dimension, each keypoint can instead contain only x and y. Ultralytics officially supports pose datasets with both two-dimensional and three-dimensional keypoint definitions.
Difference Between Detection and Pose Datasets
A normal YOLO detection label contains:
class_id x_center y_center width height
This tells the model which object is present and where its bounding box is located.
A pose label contains the same detection information plus keypoints:
class_id x_center y_center width height kp1_x kp1_y kp1_v ...
Therefore, pose datasets provide a more detailed description of each object.
A detector may recognize that a person exists inside a bounding box. A pose model can additionally predict the positions of the person’s joints.
Role of Keypoint Annotations
Keypoint annotations teach the model the spatial structure of an object.
Each keypoint must always represent the same landmark across the complete dataset.
For example, if the first keypoint represents the nose, then the first keypoint in every relevant annotation must also represent the nose.
Consistent ordering is critical. If different images use different keypoint orders, the model receives contradictory training targets and may fail to learn meaningful pose predictions.
YOLOv8 Pose Dataset Folder Structure
A YOLOv8 Pose dataset normally separates images from their corresponding text annotations.
A common structure is:
my_pose_dataset/
├── images/
│ ├── train/
│ └── val/
├── labels/
│ ├── train/
│ └── val/
└── data.yaml
The exact folder names can vary as long as the paths declared in the YAML file are correct.
Images and Labels Directories
The images directory contains the original training images.
The labels directory contains corresponding .txt annotation files.
For example:
images/train/person001.jpg
labels/train/person001.txt
The image and label use the same base filename.
If an image contains multiple annotated objects, the corresponding text file contains multiple rows, with one annotation row for each object instance.
Ultralytics uses one text annotation file per image in its standard YOLO pose dataset format.
Training and Validation Folders
The training set is used to update model weights.
The validation set is used to evaluate model performance during and after training.
For example:
images/
├── train/
│ ├── img001.jpg
│ ├── img002.jpg
│ └── img003.jpg
└── val/
├── img101.jpg
└── img102.jpg
labels/
├── train/
│ ├── img001.txt
│ ├── img002.txt
│ └── img003.txt
└── val/
├── img101.txt
└── img102.txt
The corresponding YAML file points YOLO toward these image splits.
YOLOv8 Pose Label Format
Each annotation row represents one labeled object.
A common three-value-per-keypoint structure is:
class x_center y_center width height x1 y1 v1 x2 y2 v2 ... xN yN vN
The first five values define the object class and bounding box.
The remaining values describe its keypoints.
Class ID and Bounding Box Values
The first value is the class ID:
class_id
Class IDs normally begin at zero.
The next four values represent the bounding box:
x_center y_center width height
These values are normalized relative to the image dimensions.
For example:
0 0.500 0.520 0.300 0.700
could describe an object of class 0 centered around the middle of the image.
Keypoint X and Y Coordinates
Each keypoint has horizontal and vertical coordinates.
For example:
0.42 0.31
represents the normalized position of one landmark.
When three-dimensional keypoint labels are configured, the coordinate pair is followed by another value:
0.42 0.31 2
The number and ordering of keypoints must match the dataset’s kpt_shape configuration.
Keypoint Visibility Values
When kpt_shape uses three dimensions, each keypoint includes a visibility value in addition to x and y.
Conceptually:
x y visibility
Ultralytics describes the third dimension as a visibility flag when it is included in the pose dataset.
The exact annotation policy should remain consistent across the complete dataset.
Datasets without a visibility dimension can use two values per keypoint instead. Ultralytics’ Tiger-Pose example, for instance, uses 12 keypoints without a visibility dimension.
Understanding a YOLOv8 Pose Annotation Line
A complete pose annotation line may initially look complicated because several types of information are stored together.
Consider a simplified example containing three keypoints:
0 0.50 0.50 0.40 0.70 0.48 0.20 2 0.40 0.35 2 0.60 0.35 2
This annotation contains:
0
for the class,
0.50 0.50 0.40 0.70
for the bounding box,
and:
0.48 0.20 2
0.40 0.35 2
0.60 0.35 2
for three keypoints.
Bounding Box Annotation Structure
The bounding box portion follows:
class_id x_center y_center width height
The coordinates describe the box using its center position, width, and height rather than absolute corner coordinates.
For example:
0 0.50 0.45 0.30 0.60
means class 0 with a box whose center and dimensions are expressed relative to the image.
Keypoint Annotation Structure
After the bounding box, pose-specific landmark information begins.
With kpt_shape: [3, 3], the model expects three keypoints containing three values each:
kp1_x kp1_y kp1_v
kp2_x kp2_y kp2_v
kp3_x kp3_y kp3_v
The complete line therefore contains:
class + 4 bbox values + 9 keypoint values
If kpt_shape were [3, 2], only six keypoint values would follow because each point would contain x and y without the third visibility field.
Normalized Coordinate Values
YOLO pose labels use normalized coordinates.
For an image with width W and height H:
normalized_x = pixel_x / W
normalized_y = pixel_y / H
The same principle applies to bounding box dimensions.
For example, a point at pixel position:
x = 320
y = 240
inside a 640 × 480 image becomes:
x = 0.5
y = 0.5
This normalization makes annotations independent of the original image dimensions. Ultralytics specifies normalized bounding box centers, sizes, and keypoint positions in its standard YOLO pose labels.
YOLOv8 Pose Dataset YAML File
The dataset YAML file describes the structure of the pose dataset.
It tells Ultralytics where the training and validation images are located, which object classes exist, and how many keypoints each object contains.
Train and Validation Paths
A simple configuration can look like:
path: /datasets/custom_pose
train: images/train
val: images/val
The path defines the dataset root.
The train and val fields identify the respective image sets.
Class Names
Classes are defined through the names field.
For a single person class:
names:
0: person
For a custom animal dataset:
names:
0: dog
A multi-class pose dataset can include additional entries if the training setup is designed for them.
Keypoint Shape Configuration
The kpt_shape setting describes the keypoint structure.
For the standard 17-keypoint human pose layout with three values per point:
kpt_shape: [17, 3]
This means:
17 = number of keypoints
3 = values per keypoint
For a custom eight-point dataset using x, y, and visibility:
kpt_shape: [8, 3]
For a dataset with 12 keypoints and no visibility dimension:
kpt_shape: [12, 2]
Ultralytics uses this field to define the expected keypoint count and dimensionality.
Flip Index Configuration
flip_idx defines how keypoint indices should be remapped when an image is horizontally flipped during augmentation.
For example, suppose:
0 = nose
1 = left_eye
2 = right_eye
3 = left_shoulder
4 = right_shoulder
A possible mapping is:
flip_idx: [0, 2, 1, 4, 3]
The nose remains the nose, but left and right landmarks exchange positions.
Incorrect flip mappings can generate incorrect training targets after horizontal augmentation.
A simplified complete YAML might look like:
path: /datasets/custom_pose
train: images/train
val: images/val
names:
0: person
kpt_shape: [5, 3]
flip_idx: [0, 2, 1, 4, 3]
Ultralytics pose dataset configurations use kpt_shape and can define keypoint flip mappings for pose augmentation.
COCO Pose Format vs YOLOv8 Pose Format
COCO Pose and YOLO pose datasets can describe the same underlying objects and landmarks, but they store annotations differently.
COCO traditionally uses JSON-based annotation files, while standard Ultralytics YOLO datasets use one text file per image with normalized values.
Main Annotation Differences
A COCO-style dataset normally stores annotations inside JSON structures containing fields for images, categories, bounding boxes, and keypoints.
YOLO Pose instead uses simple text rows.
Conceptually, COCO may store information like:
{
"bbox": [x, y, width, height],
"keypoints": [x1, y1, v1, x2, y2, v2]
}
YOLO stores the converted information in a corresponding .txt file:
class x_center y_center width height kp1_x kp1_y kp1_v ...
Another important difference is coordinate representation: standard YOLO pose labels use normalized values, whereas COCO annotations typically store image-space values before conversion. The official Ultralytics conversion documentation highlights the move from COCO’s JSON representation to one YOLO text file per image with normalized coordinates.
Converting COCO Pose Data to YOLO Format
Ultralytics provides conversion functionality for COCO-format datasets.
The converter supports a use_keypoints option specifically for pose annotations.
A conceptual example is:
from ultralytics.data.converter import convert_coco
convert_coco(
labels_dir="annotations/",
save_dir="converted/",
use_keypoints=True
)
The conversion process transforms COCO annotation data into the text-based format expected by standard Ultralytics pose training.
After conversion, inspect several labels manually before beginning a long training run.
Creating a Custom YOLOv8 Pose Dataset
Creating a high-quality custom pose dataset requires more than converting files into the correct syntax.
You must first define what each landmark represents and then apply those definitions consistently.
Define Custom Keypoints
Create a fixed keypoint list before annotation begins.
For example:
0 = nose
1 = left_eye
2 = right_eye
3 = left_front_paw
4 = right_front_paw
5 = left_back_paw
6 = right_back_paw
7 = tail_base
The order becomes part of your dataset definition.
If the dataset uses eight landmarks, configure:
kpt_shape: [8, 3]
if each keypoint includes three values.
Annotate Images
For every object instance, annotate:
- its class,
- its bounding box,
- every required keypoint,
- visibility information if used.
The annotations should accurately reflect the object even under different viewpoints and poses.
Special care is required for occluded or partially visible landmarks because inconsistent handling can reduce prediction quality.
Organize Labels and Images
After annotation, organize the exported files into YOLO-compatible folders.
For example:
custom_pose/
├── images/
│ ├── train/
│ └── val/
├── labels/
│ ├── train/
│ └── val/
└── custom_pose.yaml
Make sure image filenames match their label filenames:
frame_001.jpg
frame_001.txt
Validate the Dataset Before Training
Before starting full training, verify:
- every class ID is valid,
- bounding boxes are correct,
- keypoints appear in the correct order,
- coordinate values are normalized,
- the number of keypoints matches
kpt_shape, - flip mappings are correct,
- training and validation paths exist.
It is also useful to visualize several annotations.
A visually incorrect landmark can be much easier to identify on an image than by inspecting a long row of numbers.
For a quick pipeline sanity check, Ultralytics provides COCO8-Pose, a very small pose dataset specifically suited for testing and debugging pose workflows.
Common YOLOv8 Pose Dataset Errors
Dataset-format mistakes are a common reason custom pose training fails or produces poor predictions.
Incorrect Number of Keypoints
Suppose your YAML declares:
kpt_shape: [17, 3]
Then each annotated object must contain data for the expected 17 keypoints.
If one label contains only 15 landmarks or another contains 18, the dataset does not match its configuration.
The same applies to dimensionality.
[17, 3] and [17, 2] are not interchangeable because they represent different numbers of values per landmark.
Invalid Coordinate Values
Normalized coordinates should correspond correctly to the image dimensions.
Common mistakes include:
x = 450
y = 300
being written directly into a YOLO label where normalized values are expected.
Another common error is dividing x coordinates by image height rather than width, or y coordinates by width rather than height.
Incorrect normalization can place keypoints far from their intended positions.
Missing Label Files
Image and label files should correspond correctly.
If:
images/train/example.jpg
has an annotated object, its expected label should be available under the corresponding labels directory:
labels/train/example.txt
Also verify that your annotation tool did not save labels using unexpected extensions or filenames.
Incorrect YAML Configuration
Typical YAML problems include:
- incorrect dataset root,
- invalid train path,
- invalid validation path,
- incorrect class names,
- wrong
kpt_shape, - incorrect
flip_idx.
For example, using:
kpt_shape: [17, 3]
for a dataset containing eight custom keypoints will create a structural mismatch.
Always make the YAML describe the actual annotations rather than copying settings from another dataset without modification.
FAQs About YOLOv8 Pose Dataset Format
What format does YOLOv8 Pose use?
Standard Ultralytics YOLO pose datasets use one text label file per image. Each annotation row contains a class index, normalized bounding box information, and normalized keypoint coordinates. Keypoints may contain two values (x, y) or three values (x, y, visibility) depending on the dataset configuration.
What does a YOLOv8 Pose label file contain?
A pose label contains one row for each object instance.
A common format is:
class x_center y_center width height kp1_x kp1_y kp1_v kp2_x kp2_y kp2_v ...
The exact number of values depends on the number of keypoints and whether the dataset uses a visibility dimension.
Are YOLOv8 Pose coordinates normalized?
Yes. In the standard Ultralytics YOLO pose label format, object center coordinates, bounding box dimensions, and keypoint coordinates are normalized relative to the image dimensions.
What does the visibility value mean in pose labels?
When a pose dataset uses three values per keypoint, the third value is a visibility flag associated with that landmark. Datasets can also be configured without this third dimension, in which case each keypoint contains only x and y coordinates.
Can YOLOv8 Pose use custom keypoints?
Yes. Ultralytics supports custom pose datasets with user-defined keypoint layouts. The number and dimensionality of the landmarks are configured through kpt_shape, so a custom model does not have to use the standard 17 human COCO keypoints.
How do I create a dataset YAML file for YOLOv8 Pose?
Define the training and validation paths, class names, keypoint shape, and appropriate flip mapping.
For example:
path: /datasets/my_pose_dataset
train: images/train
val: images/val
names:
0: custom_object
kpt_shape: [6, 3]
flip_idx: [1, 0, 3, 2, 5, 4]
The values must match your actual dataset annotation structure.
Can COCO pose annotations be converted to YOLOv8 format?
Yes. Ultralytics provides COCO conversion tools that support pose annotations. The convert_coco utility includes a use_keypoints parameter that enables conversion of COCO keypoint data into YOLO-compatible pose labels.
Conclusion
The YOLOv8 Pose dataset format combines standard object detection labels with keypoint annotations. Each object is represented by a class ID, normalized bounding box coordinates, and a fixed set of landmark coordinates. Pose datasets can use either two-dimensional keypoints or three-dimensional keypoints that include a visibility value.
A successful custom dataset depends on more than correct folder names. The number and order of keypoints must remain consistent, kpt_shape must match the labels, flip_idx must correctly map symmetrical landmarks, and all coordinate values must be represented correctly.
For datasets originally stored in COCO JSON format, Ultralytics provides conversion utilities that can transform pose annotations into the standard YOLO text-based representation.
Carefully validating these elements before training can prevent many common errors and gives a YOLOv8 Pose model a reliable foundation for learning custom keypoints.
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.