Introduction

A confusion matrix is much easier to interpret when the rows and columns are labeled with class names. In scikit-learn, you usually control that in one of two ways: pass the class order explicitly to confusion_matrix, and use ConfusionMatrixDisplay with display_labels when plotting. If you skip the labels, the matrix is still correct, but it is much easier to misread.

Build the Matrix with an Explicit Label Order

The labels argument controls the row and column order.

1from sklearn.metrics import confusion_matrix
2
3y_true = ["cat", "dog", "cat", "dog"]
4y_pred = ["cat", "cat", "cat", "dog"]
5labels = ["cat", "dog"]
6
7cm = confusion_matrix(y_true, y_pred, labels=labels)
8print(cm)

This matters because class order is part of the meaning of the matrix. If you want the matrix to print in a predictable order, say so explicitly.

Print It with Labels Using a DataFrame

A convenient text representation is to wrap the matrix in a pandas DataFrame.

1import pandas as pd
2from sklearn.metrics import confusion_matrix
3
4labels = ["cat", "dog"]
5cm = confusion_matrix(y_true, y_pred, labels=labels)
6
7cm_df = pd.DataFrame(cm, index=labels, columns=labels)
8print(cm_df)

Now the output has row and column headers, which makes logs, notebooks, and console output easier to read.

Plot It with ConfusionMatrixDisplay

For visual output, use scikit-learn's display helper.

1import matplotlib.pyplot as plt
2from sklearn.metrics import ConfusionMatrixDisplay, confusion_matrix
3
4labels = ["cat", "dog"]
5cm = confusion_matrix(y_true, y_pred, labels=labels)
6
7disp = ConfusionMatrixDisplay(confusion_matrix=cm, display_labels=labels)
8disp.plot(cmap="Blues")
9plt.show()

The display_labels argument is what puts the class names on the axes of the chart.

If you are sharing the chart with other people, explicit labels are often more important than the raw counts. Without labels, readers may not know which class order the matrix used.

Be Careful About Label Order and Missing Classes

If the test set does not contain every class, scikit-learn may still produce a smaller matrix unless you provide the full label list. That can make comparisons across runs confusing.

Explicit labels solve that by forcing a stable axis definition even when some classes are absent in a particular batch.

This is especially important in reporting pipelines, where a changing matrix shape is harder to compare over time than a fixed labeled layout.

Binary and Multiclass Follow the Same Idea

The same label-handling pattern works for binary and multiclass classification. The only difference is matrix size.

What matters is not the number of classes but whether the human reading the result can map each row and column back to the intended class reliably.

You can also pair the matrix with a classification report so the labels and summary metrics refer to the same class ordering.

from sklearn.metrics import classification_report

print(classification_report(y_true, y_pred, labels=labels, target_names=labels))

That extra report does not replace the confusion matrix, but it does make the labeled output easier to discuss in terms of precision, recall, and support for the same classes.

It also reduces reporting ambiguity later.

Common Pitfalls

• Printing the raw matrix without recording which class order was used.
• Assuming scikit-learn will always use the class order you expect.
• Forgetting display_labels when plotting the matrix.
• Comparing confusion matrices across runs without fixing the label order.
• Interpreting rows and columns backwards because the labels were not shown clearly.

Summary

• Use labels= in confusion_matrix to control class order.
• Wrap the matrix in a pandas DataFrame if you want labeled text output.
• Use ConfusionMatrixDisplay with display_labels for plots.
• Pass the full class list when you want stable matrix shape across runs.
• Labeled axes are not cosmetic; they are part of making the result interpretable.