---
id: beniget
version: "0.5.0"
license: BSD 3-Clause
license_treatment: permissive
maintenance: active
---

# beniget — Extract semantic information about static Python code

License: permissive · Maintenance: active · Downloads: 802.3K/mo

## What it is and what it does

Beniget is a static analysis library that extracts semantic information from Python abstract syntax trees. It provides three main analyses: Ancestors (maps each node to its enclosing nodes), DefUseChains (maps definitions to their uses), and UseDefChains (maps uses back to their definitions). It works across Python 3.6+ by relying on gast for cross-version AST abstraction, and as of version 0.5.0 also supports the standard library ast module.

The library is designed as a building block for writing static analyzers, compilers, and code transformation tools. Common use cases include detecting unused imports, finding decorated functions, gathering class attributes, computing variable capture in closures, and tracing instruction dependencies. It handles the semantic complexity of Python's scoping rules and name binding, though it cannot track dynamic lookups through eval() or globals().

Use it for:

- Detect unused imports and dead code by analyzing definition-use chains at module scope.
- Find all functions decorated with a specific decorator by traversing decorator uses and their parent nodes.
- Gather all attributes assigned to self in a class by walking method parameters and attribute accesses.
- Compute identifiers captured by inner functions and lambdas from outer scopes.
- Trace the set of statements required to compute a function by combining use-def chains with ancestor analysis.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Beniget performs compile-time analysis on Python abstract syntax trees, extracting semantic information like definition-use chains, use-definition chains, and ancestor relationships to support static analysis and code transformation tools.

Yes. Beniget is a solid, actively maintained library for static Python code analysis with low install friction and no known vulnerabilities. It fills a specific niche—semantic AST analysis—and is well-suited for anyone building linters, compilers, or code transformation tools. The permissive BSD license poses no barrier. Install it if you need to reason about Python code structure and data flow.

## Install

pip install beniget
uv add beniget
poetry add beniget

## Installing beniget

Before you install: Low friction: pure Python wheel with a single runtime dependency (gast). Active maintenance with a recent release (258 days ago) and steady repository activity.

License in practice: BSD 3-Clause is permissive; you can use, modify, and distribute beniget with minimal restrictions, provided you include the license notice.

Quickstart:

import beniget
import gast as ast

code = "from math import cos, sin; print(cos(3))"
module = ast.parse(code)
duc = beniget.DefUseChains()
duc.visit(module)
for name in module.body[0].names:
    if not duc.chains[name].users():
        print(f"Unused: {name.name}")

Requires Python 3.6 or later; gast is a runtime dependency.

Verify before relying:

- Whether the standard library ast support (added in 0.5.0) is production-ready or still experimental.
- Performance characteristics on large codebases or deeply nested AST structures.

## Package facts

- License: BSD 3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 802.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python ast analysis, definition use chains, static code analysis, python compiler building, semantic ast extraction, code flow analysis, python ast traversal, ast-analysis, static-analysis, compiler-tools

[View on SkillFed](https://skillfed.io/packages/beniget) · [View on PyPI](https://pypi.org/project/beniget/)