pretty-confusion-matrix: a plotting wrapper for scikit-learn confusion matrices

The gap it fills: turning an array into a labelled figure

scikit-learn already ships confusion_matrix, and matplotlib already ships imshow. The missing piece is the twenty or so lines of glue that map class names onto tick labels, attach a colour bar, annotate each cell with its count, and pick a colormap that does not wash out low values. pretty-confusion-matrix packages that glue as two functions. The README describes the module as getting "a pretty print confusion matrix from a NumPy matrix or from 2 NumPy arrays (y_test and predictions)", which is an accurate statement of scope. The target user is someone who has already done the modelling and now needs a figure for a report, a notebook, or a paper. The README's own reference section points at the MATLAB plotconfusion function and a Stack Overflow answer about string axis labels, which tells you the author was solving a specific annoyance rather than building an evaluation framework. If you need metrics, this is the wrong library. If you need a picture, it is a short one.

Two entry points and the data flow behind them

The public surface is two functions. pp_matrix takes a pandas DataFrame whose index and columns are the class labels, so the labels arrive attached to the data. pp_matrix_from_data takes two NumPy arrays, y_test and predictions, and builds the matrix internally. The README example passes an explicit 6x6 array to pd.DataFrame with index=range(1, 7) and columns=range(1, 7), then hands that frame to pp_matrix with cmap='PuRd'. The second example passes two 108-element label vectors to pp_matrix_from_data. In both cases the plotting itself is delegated to seaborn and matplotlib, which the README names as the underlying tools. That matters for two reasons. First, the output is a matplotlib Axes object or a figure, so anything seaborn can do to it afterwards (title, size, savefig) is still available. Second, the package inherits matplotlib's rendering behaviour, including its font handling and its backend requirements. The README does not document a return value for either function, so if you need to post-process the axes, check the source or the docstring in the installed version rather than assuming.

Installation and the calls you actually type

Installation is a single PyPI command: pip install pretty-confusion-matrix. Note the distribution name uses hyphens while the import name uses underscores, so the import line is from pretty_confusion_matrix import pp_matrix, pp_matrix_from_data. The DataFrame path is three lines of setup: build the array, wrap it in pd.DataFrame with index and columns, call pp_matrix(df_cm, cmap=cmap). The vector path is a single call: pp_matrix_from_data(y_test, predic). Colormap selection is the cmap keyword on pp_matrix, and the README suggests listing what is available with from matplotlib import colormaps followed by list(colormaps). That snippet is version-sensitive: the matplotlib.colormaps registry is the modern spelling, and older matplotlib releases expose the same information through matplotlib.cm. The README does not state a minimum matplotlib version, so pinning is on you. The README also does not document a figure size parameter, a title parameter, or a normalisation parameter, which is consistent with a thin wrapper around seaborn's heatmap.

Custom class labels, and the ordering trap

Labels are the feature this package exists for. On the DataFrame path you change the index and columns arguments, and the README's example swaps range(1, 7) for a list such as ['Dog', 'Cat', 'Mouse', 'Fox', 'Bird', 'Chicken']. On the vector path you pass a columns argument: columns = ['Dog', 'Cat', 'Mouse', 'Fox', 'Bird'] followed by pp_matrix_from_data(y_test, predic, columns). The README is explicit that this parameter is positional in the sense that matters: "the order must be the same of the data representation", with Dog assigned to class 0, Cat to class 1, and so on. There is no label lookup and no validation against the values present in y_test. If your labels are strings in the data rather than integers, or if your class indices are not contiguous from zero, the axis labels will silently disagree with the cells. That is the single most likely way to produce a wrong figure with this library, and it fails quietly. The README's third argument is also shown positionally in the example, so keyword usage is not demonstrated; check the signature before assuming columns= works as a keyword.

What it does not do

There is no normalisation. The README shows raw counts only, and neither entry point is documented with a normalize or percentages argument, so row-normalised matrices (the form most useful when classes are imbalanced) require you to divide the array before plotting. There are no derived metrics: no precision, recall, F1, or per-class accuracy is computed or displayed, and the package does not import scikit-learn's metrics module in any example shown. There is no multi-label or multilabel-indicator support. There is no handling of the case where y_test and predictions have different lengths. There is no documented behaviour for a DataFrame with a non-square shape or with mismatched index and column labels. The README also does not describe a test suite beyond the badges, and the badges themselves are not evidence of correctness. None of this is a defect in a plotting helper, but it does mean the package cannot be the only confusion-matrix tool in a serious evaluation pipeline. It is the last step, not the analysis.

The alternative already in your environment

scikit-learn's ConfusionMatrixDisplay is the obvious comparison, and the difference is architectural rather than cosmetic. ConfusionMatrixDisplay.from_estimator or from_predictions computes the matrix, stores it on the display object, and exposes .confusion_matrix and .im_ so you can read values back out after plotting. It supports a normalize parameter ('true', 'pred', 'all') and a values_format argument for controlling cell text. pretty-confusion-matrix instead asks you to bring a finished DataFrame or two arrays, and its output is a figure with no documented data attribute. The trade-off is real in both directions. scikit-learn gives you normalisation and a retrievable matrix, but its default styling is plainer and its API is tied to the scikit-learn release cycle. pretty-confusion-matrix gives you seaborn's aesthetics and matplotlib colormaps with almost no API to learn, at the cost of doing the metric work yourself. If your project already depends on scikit-learn, adding this package means adding a second plotting path for a figure you could already produce.

Maintenance, releases and licence

The repository is not archived, and the release list shows 0.7.3, 0.8.0 and 0.8.1 within roughly a week in May 2026, with a push to master in July 2026. The 0.8.0 and 0.8.1 release notes are described as Zenodo DOI and citation-file changes, which means those two releases are about making the package citable rather than changing plotting behaviour. That is useful context for upgrade planning: the version number moved without the drawing code necessarily moving. The package is still on a 0.x line, so the README gives no compatibility promise between minor versions. The licence is Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved; the LICENSE file is linked from the README. If you vendor the package or ship it inside a product, read that file rather than relying on this summary. The practical upgrade cost is low because the dependency surface is matplotlib and seaborn, but a matplotlib major release can change colormap registration and default styling, and the README does not pin either dependency.

Editorial conclusion

Adopt pretty-confusion-matrix if you already compute confusion matrices yourself (or have y_true and y_pred arrays) and want a labelled, colormapped figure in one call, especially when you need string class names on both axes and a matplotlib colormap. Do not adopt it if you need normalised rows, precision/recall/F1, multi-label handling, or a maintained API surface with a semantic versioning contract; scikit-learn's ConfusionMatrixDisplay covers those cases and is already in your dependency tree. Before relying on it, verify two things against the installed version: whether pp_matrix_from_data accepts the columns argument positionally or as a keyword, and whether your matplotlib version exposes matplotlib.colormaps, since the README's colormap-listing snippet depends on it. The package is Apache-2.0, so redistribution and modification are permitted subject to that licence's notice requirements; that is a statement about the licence text, not legal advice.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. wcipriano/pretty-print-confusion-matrix on GitHub