The YOLOv8 model YAML configuration defines how the neural network itself is constructed. It describes the backbone, detection head, layer connections, module types, repeated blocks, output channels, and model scaling behavior. Unlike data.yaml, which describes a dataset, a model YAML file acts as an architectural blueprint. The official YOLOv8 configuration uses modules such as Conv, C2f, SPPF, Concat, nn.Upsample, and Detect, with each layer described using the [from, repeats, module, args] format.
Introduction to YOLOv8 Model YAML Configuration
YOLOv8 models are not defined only by hard-coded Python classes. Ultralytics uses declarative YAML configuration files to describe how many network layers should exist and how those layers connect.
A model configuration can control:
- model depth,
- feature channels,
- backbone structure,
- feature fusion,
- output detection scales,
- number of classes,
- detection head connections.
This makes YAML useful for researchers and developers who want to inspect or modify the YOLOv8 architecture without rewriting the entire model definition.
The official YOLOv8 detection configuration produces P3/8, P4/16, and P5/32 detection features.
What Is a YOLOv8 Model YAML File?
A YOLOv8 model YAML file is a configuration file that tells Ultralytics how to construct the neural network.
A simplified structure looks like:
nc: 80
backbone:
- [-1, 1, Conv, [64, 3, 2]]
- [-1, 1, Conv, [128, 3, 2]]
- [-1, 3, C2f, [128, True]]
head:
- [-1, 1, nn.Upsample, [None, 2, nearest]]
- [[-1, 4], 1, Concat, [1]]
- [[15, 18, 21], 1, Detect, [nc]]
Each entry represents one layer or module in the network.
Role of the Model YAML File
The model YAML determines the architecture that Ultralytics builds.
It can define:
Input
↓
Backbone
↓
Feature Extraction
↓
Feature Fusion
↓
Detection Head
↓
Predictions
Changing the model YAML can therefore change the actual neural network.
For example, you can:
- add an extra detection scale,
- increase repeated C2f blocks,
- change channel widths,
- add a different backbone module,
- modify feature connections.
Ultralytics describes the model YAML as the architectural blueprint that defines layer connections, module parameters, and scaling behavior.
Model YAML vs Data YAML
These files serve completely different purposes.
Model YAML:
Defines neural network architecture
It contains information such as:
nc:
backbone:
head:
scales:
Data YAML:
Defines the dataset
It normally contains:
path:
train:
val:
names:
So:
model.yaml → What network should be built?
data.yaml → What data should the network train on?
During custom training, both may be involved.
YOLOv8 Model YAML Structure
A YOLOv8 model configuration is primarily divided into architecture parameters, a backbone, and a head.
A conceptual structure is:
nc: 80
scales:
# model scaling information
backbone:
# feature extraction layers
head:
# feature fusion and prediction layers
Number of Classes
The nc parameter specifies the number of object classes:
nc: 80
For a custom three-class architecture:
nc: 3
The detection head uses this information when constructing class outputs.
In normal Ultralytics training, the class count in the model can also be overridden based on the dataset configuration when necessary, so users generally do not need to maintain a separate architecture file solely to change dataset classes.
Backbone Configuration
The backbone extracts increasingly high-level features from the image.
The official YOLOv8 backbone includes layers such as:
- [-1, 1, Conv, [64, 3, 2]]
- [-1, 1, Conv, [128, 3, 2]]
- [-1, 3, C2f, [128, True]]
- [-1, 1, Conv, [256, 3, 2]]
- [-1, 6, C2f, [256, True]]
and eventually:
- [-1, 1, SPPF, [1024, 5]]
The official YOLOv8 configuration uses convolutional downsampling, repeated C2f modules, and an SPPF module at the end of the main backbone.
Head Configuration
The YOLOv8 head combines features from different backbone stages.
It uses:
- upsampling,
- concatenation,
- C2f processing,
- downsampling,
- multi-scale feature outputs,
- Detect module.
For example, the official configuration includes:
- [-1, 1, nn.Upsample, [None, 2, "nearest"]]
- [[-1, 6], 1, Concat, [1]]
- [-1, 3, C2f, [512]]
This combines high-level and lower-level features before detection.
Understanding YOLOv8 YAML Layer Definitions
Every architecture entry follows the same basic pattern:
[from, repeats, module, args]
Ultralytics documents this as the standard declarative format used for defining model layers.
From, Repeats, Module, and Arguments
Consider:
- [-1, 3, C2f, [128, True]]
This can be interpreted as:
from = -1
repeats = 3
module = C2f
args = [128, True]
From
Defines which previous layer provides the input.
-1
means the immediately previous layer.
A list can combine multiple layers:
[[ -1, 6 ], 1, Concat, [1]]
This tells the network to combine the output of the previous layer and layer 6.
Repeats
Defines how many times the module is repeated before depth scaling.
For example:
3
means the architecture defines three repeated operations for that block before model scaling is applied.
Module
Defines the PyTorch or Ultralytics layer type:
Conv
C2f
SPPF
Concat
Detect
nn.Upsample
Arguments
Provide constructor settings for the module.
For example:
[64, 3, 2]
in a Conv entry typically represents the configured output channels, kernel size, and stride, with Ultralytics resolving required input-channel arguments during model parsing.
How Layers Connect Together
The from value controls feature flow.
For example:
- [-1, 1, Conv, [256, 3, 2]]
takes input from the immediately previous layer.
A connection like:
- [[-1, 4], 1, Concat, [1]]
combines:
Output from previous layer
+
Output from layer 4
↓
Concat
These skip and feature-fusion connections are important for combining semantic information from deeper layers with spatial detail from shallower layers.
Depth and Width Scaling
Ultralytics model YAML files support compound scaling so related model sizes can reuse the same architecture definition.
Scaling can adjust:
- number of repeated layers,
- channel width,
- maximum channels.
Conceptually:
scales:
n: [depth, width, max_channels]
s: [depth, width, max_channels]
m: [depth, width, max_channels]
The model YAML guide explains that repetition counts and channel arguments can be scaled according to a selected model variant’s depth and width multipliers.
This allows one architecture family to produce models with different computational sizes.
YOLOv8 Backbone Configuration
The YOLOv8 backbone progressively reduces spatial resolution while increasing feature abstraction.
Convolution Layers
A typical convolution entry is:
- [-1, 1, Conv, [64, 3, 2]]
The stride of 2 reduces spatial dimensions.
Conceptually:
640 × 640
↓
320 × 320
↓
160 × 160
↓
80 × 80
Downsampling allows deeper network stages to learn increasingly abstract visual patterns while reducing computational cost.
The official YOLOv8 configuration uses successive convolutional downsampling stages before P3, P4, and P5 feature levels.
C2f Modules
YOLOv8 uses the C2f module extensively throughout its backbone and head.
For example:
- [-1, 3, C2f, [128, True]]
and:
- [-1, 6, C2f, [256, True]]
C2f is a CSP-inspired feature-processing module used to build deeper feature representations while maintaining efficient feature flow.
The official YOLOv8 YAML repeatedly uses C2f blocks at multiple feature resolutions.
SPPF Module
At the end of the standard YOLOv8 backbone appears:
- [-1, 1, SPPF, [1024, 5]]
SPPF stands for Spatial Pyramid Pooling Fast.
It increases receptive-field diversity by applying sequential pooling operations and combining information from multiple effective receptive-field sizes.
In the official YOLOv8 configuration, SPPF is the last primary backbone block before the head starts processing and combining features.
YOLOv8 Detection Head Configuration
The detection head combines backbone outputs and creates final predictions across multiple resolutions.
Feature Upsampling and Concatenation
A typical head begins by upsampling:
- [-1, 1, nn.Upsample, [None, 2, "nearest"]]
Then it combines the upsampled tensor with an earlier backbone feature:
- [[-1, 6], 1, Concat, [1]]
Conceptually:
Deep Feature
↓
Upsample
↓
Concat ← Earlier Backbone Feature
↓
C2f
The head repeats this process to produce features suitable for objects of different sizes.
Multi-Scale Detection Layers
The standard YOLOv8 detection architecture generates predictions using three feature scales:
P3/8
P4/16
P5/32
These feature maps provide different spatial resolutions.
Conceptually:
P3 → smaller objects
P4 → medium objects
P5 → larger objects
This should be treated as a useful intuition rather than a strict rule because objects can be predicted across scales.
The official YOLOv8 detection YAML explicitly identifies P3/8, P4/16, and P5/32 output levels.
Detect Module Configuration
The final detection layer combines selected feature maps.
Conceptually:
- [[15, 18, 21], 1, Detect, [nc]]
The list:
[15, 18, 21]
specifies feature layers feeding the detector.
Detect then produces the final object detection outputs for the configured class count.
YOLOv8 uses an anchor-free split Ultralytics detection head.
How to Customize a YOLOv8 Model YAML File
The YAML architecture can be edited to create custom network designs.
However, architecture changes should be made carefully because every layer affects downstream tensor shapes and feature connections.
Change the Number of Classes
A custom model file may define:
nc: 5
for five object categories.
However, when training against an Ultralytics dataset, the model can use the dataset’s configured class count, so editing the architecture file only to change classes is often unnecessary.
A full custom YAML becomes more useful when architecture changes are also required.
Add or Remove Layers
You can add another layer:
- [-1, 1, Conv, [256, 3, 1]]
or another repeated module:
- [-1, 3, C2f, [256]]
But adding a layer changes layer indices.
Suppose the head contains:
- [[-1, 6], 1, Concat, [1]]
If earlier layers are inserted or removed, index 6 may no longer reference the feature map you intended.
All downstream connections should therefore be reviewed after architecture modifications.
Modify Model Depth and Width
Depth can be modified by changing repeated blocks:
- [-1, 3, C2f, [256]]
to:
- [-1, 6, C2f, [256]]
Width can be modified by changing channels:
[256]
to:
[384]
However, Ultralytics’ model scaling system is usually preferable when creating consistent Nano, Small, Medium, Large, and Extra Large variants because scaling automatically adjusts repeated blocks and channels based on configured multipliers.
Create a Custom YOLOv8 Architecture
A custom architecture could include:
nc: 3
backbone:
- [-1, 1, Conv, [64, 3, 2]]
- [-1, 1, Conv, [128, 3, 2]]
- [-1, 3, C2f, [128, True]]
- [-1, 1, Conv, [256, 3, 2]]
- [-1, 6, C2f, [256, True]]
- [-1, 1, SPPF, [256, 5]]
head:
- [-1, 1, nn.Upsample, [None, 2, "nearest"]]
- [[-1, 2], 1, Concat, [1]]
- [-1, 3, C2f, [128]]
- [[-1], 1, Detect, [nc]]
This is only a simplified architectural example, not a drop-in replacement for the standard YOLOv8 network.
For production experiments, start from the official YOLOv8 YAML and make small controlled changes rather than rebuilding the complete architecture immediately.
How to Train a Model Using Custom YAML
Ultralytics can construct a model directly from a YAML architecture file.
Load the Model YAML in Python
Use:
from ultralytics import YOLO
model = YOLO("custom_yolov8.yaml")
Then train it:
model.train(
data="data.yaml",
epochs=100,
imgsz=640
)
Ultralytics officially supports loading a YAML architecture through the YOLO interface and training it with a dataset configuration.
Train Using the YOLO CLI
A custom architecture can also be passed through the CLI:
yolo detect train model=custom_yolov8.yaml data=data.yaml epochs=100 imgsz=640
Here:
model=custom_yolov8.yaml
defines the architecture.
data=data.yaml
defines the training dataset.
Initialize Training from Pretrained Weights
A model created from YAML normally begins with newly initialized parameters unless compatible pretrained weights are explicitly loaded.
A common Python pattern is:
from ultralytics import YOLO
model = YOLO("custom_yolov8.yaml")
model.load("yolov8n.pt")
model.train(
data="data.yaml",
epochs=100
)
This can transfer compatible parameters from pretrained weights.
However, if your custom architecture changes layer shapes, channel counts, or topology substantially, not every pretrained parameter will necessarily match.
The closer the custom architecture remains to the source architecture, the more pretrained parameters can typically be reused.
Common YOLOv8 Model YAML Errors
Most architecture errors come from invalid feature connections, incorrect module arguments, or incompatible tensor dimensions.
Invalid Layer Connections
Suppose the architecture references:
[[ -1, 15 ], 1, Concat, [1]]
but layer 15 does not exist at that stage.
The model cannot construct the required feature path.
Layer indices must refer to valid previous outputs.
Whenever you add or remove layers, verify all subsequent from references.
Incorrect Module Arguments
Every module expects specific constructor arguments.
For example:
- [-1, 1, SPPF, [1024, 5]]
uses arguments appropriate to the SPPF parser and constructor behavior.
Passing arguments intended for another module can produce initialization errors.
Ultralytics recommends checking available modules and their arguments in its module source when creating advanced custom configurations.
Channel Dimension Mismatch
Concatenation or feature processing can fail if network modifications produce incompatible tensor shapes.
For example:
Feature A:
80 × 80
Feature B:
40 × 40
cannot normally be concatenated directly along the channel dimension without first matching spatial resolution.
Similarly, a custom module may expect a specific channel count but receive a different number from the previous layer.
Ultralytics’ YAML parser handles normal model channel propagation, but custom architecture changes can still produce incompatible feature sizes.
YAML Syntax Errors
Correct YAML:
backbone:
- [-1, 1, Conv, [64, 3, 2]]
Incorrect indentation or malformed brackets can prevent parsing.
Common errors include:
- missing commas,
- missing brackets,
- incorrect indentation,
- misspelled module names,
- invalid argument types.
After editing a custom YAML, try loading it before launching a long training job:
from ultralytics import YOLO
model = YOLO("custom_yolov8.yaml")
model.info()
If the architecture builds successfully, model.info() can also help inspect layer and parameter information.
FAQs About YOLOv8 Model YAML Configuration
What is a YOLOv8 model YAML file?
A YOLOv8 model YAML file is an architectural configuration that defines the model’s backbone, head, modules, layer connections, repeated blocks, class count, and scaling information.
Ultralytics uses model YAML files as declarative blueprints for constructing neural networks.
What is the difference between model.yaml and data.yaml?
model.yaml defines the neural network architecture.
For example:
backbone:
head:
nc:
data.yaml defines the dataset:
path:
train:
val:
names:
So model YAML describes the network, while data YAML describes the training data.
Can I modify the YOLOv8 architecture using YAML?
Yes.
You can modify:
- modules,
- repeats,
- channels,
- layer connections,
- detection scales,
- backbone structure,
- head structure.
Ultralytics explicitly supports architecture customization through its model YAML system.
What do from, repeats, module, and args mean?
The standard layer format is:
[from, repeats, module, args]
from identifies the source layer or layers.
repeats defines repetition count before scaling.
module identifies the layer class.
args provides module-specific constructor arguments.
This structure is the official declarative layer format documented by Ultralytics.
How do I change the number of classes in YOLOv8 YAML?
Change:
nc: 80
to the required number:
nc: 5
However, during normal custom training, Ultralytics can adapt the model class count according to the dataset, so manually modifying the architecture file solely for a different number of classes is generally unnecessary.
Can I add custom layers to YOLOv8 YAML?
Yes, but the module must be available to the Ultralytics model parser.
For built-in modules, you can reference supported module names directly.
For a new custom module, the module must first be implemented and exposed to Ultralytics so the YAML parser can resolve its name.
The official Model YAML Configuration Guide documents custom module integration and directs developers to ultralytics/nn/modules for supported module definitions.
Can pretrained weights be used with a custom model YAML?
Yes, when compatible layers exist.
For example:
from ultralytics import YOLO
model = YOLO("custom_yolov8.yaml")
model.load("yolov8n.pt")
Compatible parameters can be transferred.
If your custom architecture changes channels, layer ordering, or module shapes significantly, some pretrained tensors may not match and therefore cannot be reused directly.
Conclusion
The YOLOv8 model YAML configuration defines the architecture of the network itself. It determines how backbone and head layers are constructed, how feature maps connect, which modules are used, and how architecture depth and width are scaled.
Each model layer follows the basic format:
[from, repeats, module, args]
The standard YOLOv8 architecture uses Conv, C2f, and SPPF modules in the backbone and combines Upsample, Concat, C2f, and Detect modules in the head. Its standard detection configuration produces predictions from P3/8, P4/16, and P5/32 feature levels.
The key distinction is:
Model YAML → neural network architecture
Data YAML → training dataset configuration
YOLOv8 model YAML files can be customized to add layers, modify feature channels, change repeated blocks, introduce additional detection scales, or create a different backbone and head. However, architecture changes should be made carefully because incorrect connections, incompatible dimensions, or unsupported arguments can prevent the model from building correctly.
For most custom experiments, the safest approach is to begin with the official YOLOv8 YAML architecture, make one controlled modification at a time, verify the model with model.info(), and only then begin full training.
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.