A YOLO label file never stores a class name — every box references a class by numeric index, and classes.txt (or data.yaml's names list) maps that index to a name purely by position. That's fine as long as the list never changes. The moment it does — two labelers used different names for the same thing, a rarely-occurring class should fold into a broader one, a class needs removing entirely — hand-editing that list is exactly the kind of mechanical, position-dependent task a text editor makes dangerously easy to get wrong.
Why hand-editing classes.txt breaks a dataset silently
Renaming an entry in place is safe: the index at that position doesn't move, so every label file referencing it still points at the right thing. Reordering, inserting in the middle, or deleting an entry is where it breaks — every class after the changed position now has a different index than the label files still expect, and every box referencing one of those shifted indices is now labeled as something else entirely. Nothing throws an error. The dataset still loads, trains, and produces a model — it's just quietly learning the wrong labels for however many classes came after the edit.
The three actions
The YOLO Class Manager works from the same three operations regardless of how many classes a dataset has:
- Rename — changes only the label text; the index is untouched, so no label file is rewritten, only
classes.txt/data.yaml. - Merge — folds one class into another, reassigning every occurrence of the source index to the target index across every label file. This is the tool for "two labelers called the same thing 'auto' and 'car'" or "these five near-identical subtypes should really be one class."
- Remove — deletes every box of that class from every label file it appears in, then compacts the remaining indices so there's no gap. This is the one operation that touches every label file that referenced the removed class, not just the class list.
Seeing the impact before committing
Before anything is written, the tool counts exactly how many boxes and how many files each planned action affects — "merging 'auto' into 'car' affects 342 boxes across 178 files," or "removing 'construction-cone' affects 12 boxes across 9 files" — computed from the dataset actually loaded, not estimated. A merge or removal that turns out to affect far more (or far fewer) of the dataset than expected is worth a second look before exporting, and this is where that shows up.
Nothing is changed until you export
The plan only exists in the browser until you download the result — your original files are read, never written to, and the corrected dataset comes back as a new .zip with every label file rewritten and a new classes.txt/data.yaml alongside it. If a plan turns out wrong, nothing about your original dataset needs undoing — it was never touched.
Where each step happens
- Deciding what needs to change — the YOLO Dataset Health Checker surfaces the class list actually present across a dataset's label files, useful when there's no
data.yamlto read it from directly. - Remapping — the YOLO Class Manager is the tool this guide is built around — rename, merge, or remove, with the impact preview above before anything is exported.
- Splitting afterward — if a merge or removal changes how rare a class is, re-check the split with the YOLO Dataset Splitter's class-balance warnings — see how to split a YOLO dataset without leakage.