Diffprivlib, IBM's general purpose Python library for differential privacy

Four parts: mechanisms, models, tools and an accountant

Diffprivlib is described as a general-purpose library for differential privacy, and its stated use cases are experimentation, exploring the impact of differential privacy on machine learning and analytics applications, and prototyping your own DP algorithms. The library's own description of its value is that it has lowered the barrier to entry for people learning the field, spawned research, and served as a benchmark for new algorithms and libraries.

Structurally it has four components, and the split matters for how you use it.

Mechanisms are the building blocks of differential privacy, used in all the models that implement it. The README is direct about their audience: mechanisms have little or no default settings and are intended for use by experts implementing their own models, though they can be used on their own for separate investigations. Models are the differentially private machine learning models, and the library covers clustering, classification, regression, dimensionality reduction and pre-processing. Tools are generic utilities for differentially private data analysis, including differentially private histograms that follow the same format as NumPy's histogram function. The Accountant is the BudgetAccountant class, which tracks privacy budget and calculates total privacy loss using advanced composition techniques.

That layout supports two very different workflows. A practitioner picks a model and sets a budget. A researcher builds a mechanism from scratch and accounts for the loss of each call.

The models behave like scikit-learn classifiers

The quick start is deliberately short, because the point of the library is that you do not need to learn a new API to try a differentially private model.

The classifier trains like an sklearn classifier. You instantiate diffprivlib.models.GaussianNB, fit it, and predict, with the same method names:

from diffprivlib.models import GaussianNB

clf = GaussianNB()
clf.fit(X_train, y_train)

The privacy level is controlled by the parameter epsilon, which is passed to the classifier at initialisation, for example GaussianNB(epsilon=0.1), and the default is epsilon = 1.0. One detail catches people out: the classifier can be run without any parameters, but doing so throws a warning, because the bounds parameter has to be specified to avoid it. Bounds are the domain of the data, and the privacy guarantee of the mechanism depends on them, so a private classifier that does not know the range of the features cannot add the right amount of noise.

The demo workflow is worth copying because it shows the trade-off directly. You sweep epsilon across five orders of magnitude and plot accuracy:

epsilons = np.logspace(-2, 2, 50)
bounds = ([4.3, 2.0, 1.1, 0.1], [7.9, 4.4, 6.9, 2.5])
accuracy = list()

for epsilon in epsilons:
    clf = GaussianNB(bounds=bounds, epsilon=epsilon)
    clf.fit(X_train, y_train)
    
    accuracy.append(clf.score(X_test, y_test))

Note also that every call to fit produces a different model, because differential privacy is randomised. Re-training on the same data changes the accuracy, so a single accuracy number is one sample from a distribution rather than a stable measurement of the model.

The accountant is where privacy loss is composed

Most differentially private code fails in the same way. Each query spends budget, the code is written so that each individual query looks fine, and nobody adds up the total. A single report can be harmless and a hundred reports over the same dataset can be identifying.

The BudgetAccountant class is the answer to that. It can be used to track privacy budget and calculate total privacy loss using advanced composition techniques, which is the accounting you need when a pipeline of private operations has to be justified as a whole rather than query by query.

This component is the one that changes how a team works, more than the models do. Once a budget is a tracked object rather than a number in a notebook, the design question becomes how much of the budget each stage of an analysis is allowed to spend, and whether the composition is accounted for across stages. The library does not impose a policy on that. It provides the arithmetic, and the choice of how to spend the budget stays with the application.

The library also ships documentation at diffprivlib.readthedocs.io and a notebooks/ directory in the repository, including the thirty second machine learning example used in the README, which is the fastest way to see the API in use.

Installing from PyPI and checking the install with pytest

The library is designed to run with Python 3, and the standard install comes from PyPI:

pip install diffprivlib

For the most recent version you can download the source or clone the repository into a directory of your choice:

git clone https://github.com/IBM/differential-privacy-library

and then install it from the project folder, either with pip install . or with the alternative python3 -m pip install . invocation:

pip install .

The library ships unit tests for pytest, and the README suggests running them from the install folder to confirm the installation works:

pytest

The packaging metadata tells you what you are pulling in. The runtime requirements are numpy >= 2.0.0, scikit-learn >= 1.4.0, scipy >= 1.13.0, joblib >= 0.16.0 and setuptools >= 49.0.0, and python_requires is set to >= 3.8. There is a docs extra pulling in sphinx and the sphinx_rtd_theme, and a separate crlibm extra, which points at the correctly rounded elementary functions used where floating point rounding error would otherwise break a bound. The project is classified as Development Status :: 4 - Beta and its licence is MIT, with the LICENSE.md file and a CITATION.bib for the reference paper.

The maintainers call the public release research and education only

The most important sentence in the README is a note, and it reads that the public release of diffprivlib is intended for research and education purposes only, with an invitation to reach out if you want to use it in a production environment.

That is a support and expectation statement rather than a legal one. The licence field is MIT, which permits commercial use in the usual way, and the package classifiers list Developers, Education and Science/Research as intended audiences. But a library that admits its own models are experimental and asks you to make contact before running it in production is telling you something about the guarantees behind the code, about who is responsible if a query leaks, and about how quickly a bug in a privacy mechanism would be patched.

This is worth taking at face value rather than working around. Differential privacy is unforgiving in a way ordinary analytics is not. A wrong noise scale does not degrade a result slightly, it removes the guarantee entirely while the output still looks plausible, and nobody notices from the output alone. A library maintained as a research and teaching resource, with a beta status classification and community-driven issue handling, is a reasonable place to prototype and an uncomfortable place to hang a compliance claim.

The version history supports that reading. Releases are 0.6.6 in April 2025, 0.6.5 in October 2024 and 0.6.4 in January 2024, so the numbering has stayed in the 0.6 line for a while, and the last push to the repository was on 2026-10-12. The project is still being worked on, just not on a release cadence you should plan around.

Where a general purpose library stops

Diffprivlib is general in the sense that it covers many mechanisms, models and analysis tasks rather than one domain. It is not general in the sense of covering the parts of a production privacy system.

The first gap is composition across a real pipeline. BudgetAccountant tracks privacy loss with advanced composition, which is the right primitive, but a production system also has to handle the case where a query is repeated on overlapping data, where a partition is redrawn, or where the same individual appears in several records. The library does not claim to solve those, and its model API is per-call.

The second gap is the surrounding infrastructure. Persistent budget state across process restarts, a query audit trail, role-based approval for spending budget, and the mapping from a legal basis to a noise scale are all application concerns. A library that returns a private result cannot carry any of them.

The third gap is the input side. The bounds argument on GaussianNB is a good illustration of how much of a real deployment has to be done before the privacy machinery can be trusted. Somebody has to know, or derive, the true range of every feature, and if that range is wrong or drifts, the noise is wrong. Diffprivlib gives you the mechanism that consumes those bounds. Deciding them, and keeping them true, stays with you.

For research, teaching and prototyping, the library does exactly what the README claims. For a production system with a privacy budget attached to it, the arithmetic is useful and the rest of the design is yours.

Editorial conclusion

Diffprivlib suits researchers, students and engineers who need a working reference implementation of differential privacy, a way to see how epsilon changes accuracy, and a budget accountant to compose privacy losses. It does not suit a production data pipeline that needs a support commitment, because the project states the public release is intended for research and education and asks production users to get in touch. Before you build on it, pin the version you tested against, read the note about bounds on GaussianNB because the privacy guarantee depends on them, and confirm that the dependency floors, numpy 2.0, scikit-learn 1.4 and scipy 1.13, match your environment.

Frequently asked questions

Official sources

1. IBM/differential-privacy-library on GitHub
2. License: MIT
3. Project website
4. README
5. Releases