Introduction

A confusion matrix is only useful if you know which row and column corresponds to which class. Misreading the label order leads to swapped precision and recall values, which can silently ruin your model evaluation. Scikit-learn's confusion_matrix function has a default ordering that may not match your expectations, so understanding how to inspect and control it is essential.

Default Label Order

By default, sklearn.metrics.confusion_matrix sorts the unique labels found in y_true and y_pred in ascending order. For numeric labels this means numerical sorting; for string labels it means alphabetical sorting.

1from sklearn.metrics import confusion_matrix
2
3y_true = [1, 0, 1, 1, 0, 1]
4y_pred = [1, 0, 0, 1, 0, 0]
5
6cm = confusion_matrix(y_true, y_pred)
7print(cm)
8# [[2 0]
9#  [2 2]]

Here the rows and columns are ordered [0, 1] because sorted([0, 1]) gives [0, 1]. Row 0 corresponds to true label 0, and row 1 corresponds to true label 1.

For string labels the same principle applies:

1y_true = ['cat', 'dog', 'cat', 'bird']
2y_pred = ['cat', 'cat', 'cat', 'dog']
3
4cm = confusion_matrix(y_true, y_pred)
5print(cm)
6# [[0 0 0]
7#  [0 2 0]
8#  [1 0 1]]
9# Order: ['bird', 'cat', 'dog'] (alphabetical)

Reading the Matrix: Rows vs Columns

The convention in scikit-learn is that rows represent true labels and columns represent predicted labels. So cm[i][j] is the count of samples whose true label is class i and whose predicted label is class j.

1# For binary classification with labels [0, 1]:
2# cm[0][0] = True Negatives
3# cm[0][1] = False Positives
4# cm[1][0] = False Negatives
5# cm[1][1] = True Positives

This means if you swap the label order, the positions of True Positives and True Negatives also swap, which changes how you read every derived metric.

Changing the Label Order with the labels Parameter

The labels parameter lets you explicitly specify which classes to include and in what order. This is the key to controlling the layout of your confusion matrix.

1y_true = ['cat', 'dog', 'cat', 'bird']
2y_pred = ['cat', 'cat', 'cat', 'dog']
3
4# Custom order: dog first, then cat, then bird
5cm = confusion_matrix(y_true, y_pred, labels=['dog', 'cat', 'bird'])
6print(cm)
7# [[0 1 0]
8#  [0 2 0]
9#  [0 0 0]]

For binary classification, a common convention is to place the positive class last so that the bottom-right cell is True Positives:

1y_true = [1, 0, 1, 1, 0, 1]
2y_pred = [1, 0, 0, 1, 0, 0]
3
4# Ensure positive class (1) is in position [1][1]
5cm = confusion_matrix(y_true, y_pred, labels=[0, 1])
6print(cm)
7# [[2 0]
8#  [2 2]]

You can also use labels to exclude certain classes by simply not including them in the list.

Visualizing with ConfusionMatrixDisplay

Scikit-learn provides ConfusionMatrixDisplay to render the matrix with proper axis labels, removing any ambiguity about which row or column belongs to which class.

1from sklearn.metrics import confusion_matrix, ConfusionMatrixDisplay
2import matplotlib.pyplot as plt
3
4y_true = ['cat', 'dog', 'cat', 'bird', 'dog', 'cat']
5y_pred = ['cat', 'cat', 'cat', 'bird', 'dog', 'dog']
6
7labels = ['bird', 'cat', 'dog']
8cm = confusion_matrix(y_true, y_pred, labels=labels)
9
10disp = ConfusionMatrixDisplay(confusion_matrix=cm, display_labels=labels)
11disp.plot(cmap='Blues')
12plt.title('Confusion Matrix with Custom Label Order')
13plt.show()

Alternatively, you can generate the display directly from predictions:

1ConfusionMatrixDisplay.from_predictions(
2    y_true, y_pred,
3    labels=['bird', 'cat', 'dog'],
4    cmap='Blues'
5)
6plt.show()

Both approaches annotate each cell with its count and label the axes, so you never have to guess which class is which.

Multi-Class Example with Specific Ordering

When working with multi-class problems, controlling order becomes even more important for readability. You might want to group related classes together:

1y_true = [0, 1, 2, 3, 0, 1, 2, 3, 0, 2]
2y_pred = [0, 1, 3, 3, 0, 2, 2, 3, 1, 2]
3
4# Group even and odd labels together
5cm = confusion_matrix(y_true, y_pred, labels=[0, 2, 1, 3])
6print(cm)

The labels parameter gives you full control over the arrangement, which is particularly useful when presenting results to stakeholders who expect a specific class ordering.

Common Pitfalls

• Assuming label order matches your training data order: The default is always sorted, not insertion-ordered. Always verify with sorted(set(y_true) | set(y_pred)).
• Mixing up rows and columns: Rows are true labels, columns are predicted labels. Reading it backwards swaps false positives with false negatives.
• Forgetting to pass labels when classes are missing from predictions: If a class appears in y_true but never in y_pred (or vice versa), the matrix dimensions can change unexpectedly. Specifying labels guarantees a consistent shape.
• Using display_labels that do not match the labels order: If you pass one order to confusion_matrix and a different order to ConfusionMatrixDisplay, the visualization will be wrong without any error.
• Not normalizing for imbalanced datasets: A raw count matrix can be misleading when class sizes differ dramatically. Use normalize='true' in ConfusionMatrixDisplay.from_predictions to see per-class recall rates.

Summary

• Scikit-learn sorts labels in ascending order by default. Check with sorted(set(y_true) | set(y_pred)) to confirm the order.
• Use the labels parameter in confusion_matrix() to explicitly set which classes appear and in what order.
• Rows represent true labels and columns represent predicted labels, so cm[i][j] counts samples that are truly class i but predicted as class j.
• Use ConfusionMatrixDisplay or ConfusionMatrixDisplay.from_predictions to render a labeled heatmap that removes all ambiguity.
• Always pass the same labels list to both the matrix computation and the display to keep them consistent.