696 stars · ISC (named in the About sidebar and on the package index) · 2.4.1 (2026-10-22), settled from the package index rather than from GitHub, which shows no releases · Track this in Scout
Compares two versions of a Python package and lists the changes that would break code calling it.
Radar check
What we found when we opened it. Every bar is one fact, with its date.
Last code pushed 23 Oct 2026, 3 days before this check.
Latest release 2.4.1 on 22 Oct 2026.
Public since September 2021, about 5 years.
701 stars and 79 forks.
69 commits and 13 new issues in the last 90 days.
54 contributors. 10 pull requests merged in 90 days.
No security policy file says how to report a problem. No published security advisories.
How the bars are scored
- Alive. Days since the last code push: a week or less 100, a month 90, three months 70, six months 50, a year 30, eighteen months 15, older 0.
- Releases. Age of the latest GitHub release, on a similar scale; no bar when the project publishes no releases.
- Maturity. Age of the project: eight years 100, five 90, three 70, two 55, one 40, six months 25, younger 10.
- Adoption. Stars on a log scale: 100,000 stars is 100, 10,000 is 80, 1,000 is 60, 100 is 40.
- Activity. Commits in the last 90 days: 300 or more 100, 100 85, 30 65, 10 45, any 25.
- Community. People who have contributed: 100 or more 100, 30 80, 10 60, 5 40, 2 25, one 10.
- Security. A published security policy 80, none 40; published advisories are listed, not scored.
Checked by Repo Radar on 26 Oct 2026 from the repository on GitHub. Covered in Edition 62.
▶Repo detailsthe review · specs · pros & cons · install
What it does
It reads a Python project and builds a description of everything it offers publicly: modules, classes, functions, and the exact shape of each signature. griffe dump writes that description out as JSON so other tools can use it. griffe check compares two versions and reports the differences that matter — for example, an argument that used to be accepted by position and is now accepted only by name, which silently breaks every caller that passed it positionally. It can compare the current code against a git reference, or compare a published package against another version fetched from the package index. In library form it offers griffe.load(), griffe.load_git() and griffe.find_breaking_changes(). It is not a type checker and not a test runner: it says what changed in the shape of the interface, and nothing about whether the code inside is correct.
Why it matters
Who it suits. Anyone who publishes a Python package that other people install. Also anyone maintaining a large internal package that several teams import, where a quiet rename causes a support ticket a week later. It suits a release process that already runs checks automatically, because this is one more command. Skip it if the code is an application nobody imports, because then nothing outside it depends on the shape of the interface.
Verdict. The best ten minutes in today's edition, and the reason it is a gem at 696 stars is that most people have never heard of it. Version 2.4.1 was published on 22 October 2026, four days before this edition, under the ISC licence. One command in a release script answers a question that is otherwise answered by a stranger's bug report. The limit to understand: it compares interfaces, so a function that keeps its signature and changes its behaviour passes the check. Pair it with tests, not instead of them. The same author's documentation generator, mkdocstrings/mkdocstrings, uses this underneath, so installing one often brings the other.
- One command reports the breaking changes before anyone else finds them.
- Can compare against a git reference or against a version on the package index.
- Small, fast and released constantly. ISC licence.
- Only sees the shape of the interface, so a changed behaviour with an unchanged signature passes.
- Python only.
- At 696 stars the community around it is small, so answers come from the documentation rather than from other people.
mkdocstrings/mkdocstrings2.1k stars, ISC; the documentation generator built on Griffe, covered in Edition 44. It publishes the interface rather than checking it.
Track this in Scout
mitmproxy/pdoc2.5k stars; generates Python documentation in one step with no configuration, and does no breaking-change analysis.
Track this in Scout
python3 -m venv venv source venv/bin/activate pip install "griffe[pypi]" griffe dump mypackage --search src griffe check mypackage --search src -b main -a HEAD --verbose
