AST Metrics for Python

AST Metrics is a static analyzer that tells you which parts of a codebase are risky to touch. This package installs it with pip, like any other dev tool: no compiler, no service. The analyzer is a single binary, downloaded once and cached.

You may not need this package. It exists for one thing: getting the analyzer through pip, so it lands in requirements.txt (or uv.lock) with the rest of your tooling and pipx run ast-metrics just works. If that is not what you are after, install the analyzer directly:

brew install ast-metrics/tap/ast-metrics    # macOS, Linux
curl -fsSL https://install.ast-metrics.dev | sh

And on pull requests, there is a ready-made action: ast-metrics/action-ast-metrics@v2.

Usage

Without installing anything:

pipx run ast-metrics analyze src

Or as a dev dependency, which pins the analyzer version in your lockfile:

pip install ast-metrics          # add it to requirements-dev.txt yourself
# or, with uv:
uv add --dev ast-metrics

ast-metrics analyze src
ast-metrics analyze --report-html=./report src

If the virtualenv's bin (or Scripts) directory is not on PATH, run it as a module instead: python -m ast_metrics analyze src. It behaves exactly like the ast-metrics command.

Everything else: ast-metrics --help, or ast-metrics.dev.

What gets analyzed

Python (.py), and, in the same run, Go, PHP, TypeScript, Rust, Java and C#. Most codebases are not made of one language, and the metrics are comparable across all of them.

In CI

- run: pipx run ast-metrics analyze --ci src

--ci writes the HTML and Markdown reports and keeps the output plain. Reports for a quality gate: --report-sarif=<file> (read by GitHub code scanning and GitLab), --report-json=<file>, --report-openmetrics=<file>.

The binary is downloaded once per version and cached in $AST_METRICS_CACHE_DIR, which defaults to $XDG_CACHE_HOME/ast-metrics or ~/.cache/ast-metrics, so caching that directory between builds removes the download entirely.

Pre-commit hook

This repository ships a .pre-commit-hooks.yaml:

repos:
  - repo: https://github.com/ast-metrics/ast-metrics-bridge-python
    rev: v0.41.1
    hooks:
      - id: ast-metrics

Without a .ast-metrics.yaml configuration file that sets requirements, ast-metrics lint has nothing to check and does nothing. Run ast-metrics init once to create one.

Configuration

All optional.

Variable	Effect
AST_METRICS_BINARY	Path to a binary to use as-is, nothing downloaded: air-gapped installs, distribution packages.
AST_METRICS_VERSION	Release tag to download, or latest. Defaults to the pinned version.
AST_METRICS_CACHE_DIR	Where binaries are cached. Defaults to $XDG_CACHE_HOME/ast-metrics, or ~/.cache/ast-metrics if unset (%LOCALAPPDATA%\ast-metrics on Windows).
HTTP_PROXY, HTTPS_PROXY, NO_PROXY	Honoured for the download by urllib, the standard-library HTTP client this package uses.

The analyzer version is pinned by this package rather than resolved to latest, so a locked requirements.txt (or uv.lock) gives a reproducible analysis. The package version matches the analyzer version it installs: ast-metrics==0.41.1 runs AST Metrics 0.41.1. To upgrade, pip install --upgrade ast-metrics or uv lock --upgrade-package ast-metrics.

Unlike npm, pip has no post-install hook: nothing is downloaded at pip install time. The binary is fetched on the first run of ast-metrics (or python -m ast_metrics), then cached for every run after that. On an air-gapped or hermetic install, where that first run cannot reach the network, install the binary yourself and set AST_METRICS_BINARY=/path/to/ast-metrics before running this package.

Contributing

See CONTRIBUTING.md. Analyzer bugs go to ast-metrics/ast-metrics; this repository is the Python bridge.

License

MIT. See LICENSE.