How to Plot Confusion Matrix in Python: A Complete Guide

Learn how to create and plot a confusion matrix in Python using scikit-learn and Seaborn so you can evaluate a classification model’s performance.

The Role of Confusion Matrices in Model Evaluation

When you build a classification model, understanding how to plot confusion matrix in Python is key to spotting systematic errors. A confusion matrix is a simple table that shows how a supervised learning algorithm performs. It lines up the true class labels with the predicted ones, so you can see not only the overall accuracy but also exactly where the model gets things wrong. Overall accuracy can be very misleading, especially with imbalanced data. For instance, a model that predicts rare system failures might reach 99% accuracy just by always saying no failure occurs.

A confusion matrix reveals this by displaying the counts of True Positives (TP), True Negatives (TN), False Positives (FP), and False Negatives (FN). Plotting the matrix lets you quickly tell if the model has many type I or type II errors, helping you decide how to improve features and tune the model.

For a closely related example, see Train Test Split in Machine Learning Python Example: Avoiding Data Leakage.

Generating Classification Data and Predictions

Before plotting a confusion matrix, we must train a model and generate predictions on a test dataset. To ensure our evaluation is mathematically sound, we will use scikit-learn to generate a synthetic classification dataset with informative features. We then perform a stratified split to preserve the class ratios in both our training and testing subsets, preventing evaluation bias.

from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
# Generate a structured synthetic dataset
X, y = make_classification(
    n_samples=1000,
    n_features=10,
    n_informative=8,
    n_redundant=2,
    random_state=42
)
# Stratified split to maintain class proportions
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, stratify=y, random_state=42
)
# Train a baseline Random Forest classifier
clf = RandomForestClassifier(random_state=42)
clf.fit(X_train, y_train)
# Generate predictions on the test set
y_pred = clf.predict(X_test)

With our true labels (y_test) and predicted labels (y_pred) ready, we can now proceed to explore the different plotting mechanisms available in Python.

For a closely related example, see Rhizosphere 16S rRNA gene amplicon data, PICRUSt2-predicted functional profiles, tuber GC-MS/MS and amino-acid data, plot-level yield and N/C analysis, postharvest storage data, and tuber mineral composition from a potato field trial with an endophytic bacterial consortium..

Plotting with Scikit-Learn ConfusionMatrixDisplay

The cleanest and most direct way to plot a confusion matrix in Python is by using scikit-learn's built-in tool: ConfusionMatrixDisplay. This utility eliminates the need to manually compute the underlying matrix before plotting, reducing the likelihood of indexing or alignment errors.

import matplotlib.pyplot as plt
from sklearn.metrics import ConfusionMatrixDisplay
# Plot directly from predictions
disp = ConfusionMatrixDisplay.from_predictions(
    y_true=y_test,
    y_pred=y_pred,
    display_labels=["Class A", "Class B"],
    cmap=plt.cm.Blues
)
plt.title("Confusion Matrix via ConfusionMatrixDisplay")
plt.show()

This method automatically handles the colour mapping, axis labels, and text annotations inside each grid square. If you already have a trained estimator instance and your test features, you can also use `ConfusionMatrixDisplay.from_estimator(clf, X_test, y_test)` to achieve the same result in a single step.

Customising the Plot with Seaborn and Matplotlib

While scikit-learn's native tools are excellent for quick validation, production-grade reports or academic papers often require highly customised styling. For these scenarios, combining the raw `confusion_matrix` calculation with Seaborn's heatmap plotting function offers maximum flexibility.

import seaborn as sns
from sklearn.metrics import confusion_matrix
# Compute the raw numerical confusion matrix
cm = confusion_matrix(y_test, y_pred)
# Set up the matplotlib figure size
plt.figure(figsize=(8, 6))
# Plot the heatmap with specific formatting
sns.heatmap(
    cm, 
    annot=True, 
    fmt="d", 
    cmap="Purples",
    xticklabels=["Class A", "Class B"],
    yticklabels=["Class A", "Class B"]
)
plt.ylabel("Actual Label")
plt.xlabel("Predicted Label")
plt.title("Custom Seaborn Confusion Matrix")
plt.show()

Using Seaborn allows you to easily adjust font sizes, control decimal formatting (via the `fmt` parameter, where 'd' denotes integer formatting), and integrate the plot seamlessly into larger multi-panel figures.

Normalisation and Handling Imbalanced Datasets

When working with imbalanced datasets, absolute numbers in a confusion matrix can obscure poor performance on minority classes. For instance, if Class A has 500 samples and Class B has only 10, a small absolute error of 5 misclassifications in Class B represents a massive 50% failure rate, which might look negligible next to Class A's numbers.
To resolve this, you should normalise the confusion matrix. Normalisation can be performed along the true rows (showing recall), predicted columns (showing precision), or over the entire dataset.

# Plot normalized confusion matrix (row-wise/recall style)
disp_norm = ConfusionMatrixDisplay.from_predictions(
    y_true=y_test,
    y_pred=y_pred,
    display_labels=["Class A", "Class B"],
    cmap=plt.cm.Greens,
    normalize="true",
    values_format=".2f"
)
plt.title("Normalized Confusion Matrix (Recall)")
plt.show()

Setting `normalize='true'` ensures that each row sums to 1.0, making it immediately clear what proportion of each actual class was correctly identified by your machine learning model.

For a closely related example, see How to Improve Machine Learning Model Accuracy: A Systematic MLOps Guide.

Troubleshooting Common Plotting and Alignment Issues

When plotting confusion matrices, developers frequently encounter alignment or dimension mismatches. The most common error is `ValueError: Found input variables with inconsistent numbers of samples`. This occurs when the length of your true labels array does not match the length of your predictions array. Always verify your array shapes using `y_test.shape` and `y_pred.shape` before passing them to the plotting functions. Another frequent issue is label ordering. If your classes are non-numeric or categorical, scikit-learn and Seaborn may order them alphabetically by default, which might not match your logical ordering.

To enforce a specific sequence, use the explicit `labels` parameter in `confusion_matrix(y_test, y_pred, labels=['Class B', 'Class A'])`. This guarantees that your matrix coordinates map correctly to your intended domain logic.