chokkin

日本語

Find unused files, dependencies, and public symbols in Python projects.

chokkin is a reachability analyzer for whole Python projects — a Knip-like experience for Python. It builds a project-wide graph from your manifests, source code, and tool configs, then reports what nothing reaches: run uvx chokkin with zero configuration, and tighten things up with precise settings and CI integration as you go.

Why chokkin?

Existing tools each cover one slice of the problem:

Ruff     : per-file, syntax-level linting
Vulture  : Python AST-based dead code detection
deptry   : consistency between dependency manifests and imports
chokkin    : unused files, dependencies, and public symbols from the whole project graph

chokkin is not a style/lint tool. It answers a different question: starting from your entry points, what can actually be reached — and what is just sitting there? It reads pyproject.toml (including Poetry/PDM/Hatch dependency sections), requirements files, uv lockfiles, and framework/tool configs (Django, FastAPI, pytest, tox, nox, pre-commit, GitHub Actions, …) to build that picture.

Quick start

uvx chokkin

No configuration needed. On first run, chokkin discovers your manifests (pyproject.toml, setup.cfg, setup.py, requirements*.txt, and one lockfile: uv.lock, pylock.toml, poetry.lock, or pdm.lock), infers your layout (src/flat, tests, scripts, docs), infers entry points, builds the import graph, and reconciles it against your declared dependencies:

chokkin 0.7.2

Project: acme-api
Config : pyproject.toml
Mode   : app, production=false

Unused files  2
  src/acme/legacy.py       src/acme/legacy.py     file `src/acme/legacy.py` is not reachable from any entry root
  src/acme/old_handlers.py src/acme/old_handlers.py file `src/acme/old_handlers.py` is not reachable from any entry root

Unused dependencies  3
  boto3                    pyproject.toml         declared in project.dependencies[1], no reachable import, config, or binary usage found
  python-dotenv            pyproject.toml         declared in project.dependencies[3], no reachable import, config, or binary usage found
  rich                     pyproject.toml         declared in project.dependencies[2], no reachable import, config, or binary usage found

Missing dependencies  1
  src/acme/config.py:3 yaml src/acme/config.py:3   imported pyyaml in src/acme/config.py:3 (no lockfile — transitive check skipped) but not declared in matching dependency context

Unused exports  2
  acme.auth:OldTokenBackend src/acme/auth.py:5     public class `OldTokenBackend` in `acme.auth` is not referenced from outside the module
  acme.utils:legacy_slugify src/acme/utils.py:5    public function `legacy_slugify` in `acme.utils` is not referenced from outside the module

Summary: 8 issues

What it checks

Because any module top-level name is importable in Python, unused_export starts out as a preview rule (info-level in library mode) rather than a hard error. In library mode, a name its own module reads (a TypeVar, a type alias, a helper) is not reported either, since outside callers can reach it through the module's API.

CLI

uvx chokkin
uvx chokkin --production
uvx chokkin --strict
uvx chokkin --no-exit-code
uvx chokkin --include CHK002,CHK003
uvx chokkin --exclude CHK006
uvx chokkin --reporter json
uvx chokkin --reporter markdown
uvx chokkin --reporter github
uvx chokkin --reporter sarif
uvx chokkin --confidence likely
uvx chokkin --fix
uvx chokkin --fix --dry-run
uvx chokkin --fix --allow-remove-files
uvx chokkin --fix --add-missing
uvx chokkin --baseline chokkin-baseline.json
uvx chokkin --baseline chokkin-baseline.json --update-baseline
uvx chokkin --no-cache
uvx chokkin --explain CHK002:boto3
uvx chokkin --trace src/acme/legacy.py
uvx chokkin --probe              # steps 1–4 summary only
uvx chokkin --init

Key flags:

• --production — drop dev/test/docs/lint/type contexts and judge reachability from runtime context only. Dev-only files and dependencies are no longer reported, and "unused in production" becomes strict.
• --strict — direct imports of transitive dependencies always error, workspace members must declare their own dependencies, CHK003 also includes type/test/docs/dev imports, unused environment-marker dependencies error, and maybe-confidence issues are shown.
• --no-exit-code — exit 0 even when issues are found (config/CLI errors still exit 2, internal errors 3). Useful during adoption and for GitHub Actions summaries.
• --fix — apply conservative fixes for certain dependency findings; add --allow-remove-files to also remove certain unreachable files. --add-missing adds Certain CHK003 findings to non-Poetry [project].dependencies when the distribution is unambiguous; workspace findings are inserted into the member pyproject.toml when that member manifest was inventoried. Unsupported cases are reported as skipped fixes with details on stderr.
• --baseline PATH / --update-baseline — freeze current issues in a baseline file and suppress matching issues on later runs so CI fails only on new findings.
• --no-cache — disable Phase 2 cache reads/writes. Parse and manifest/config scan cache units are enabled by default under the project root and are conservative: corrupt or stale entries are treated as misses.
• --no-auto-workspace — do not treat nested pyproject.toml files with a [project] name as workspace members when the repository declares no uv or chokkin workspace (see workspace mode below).
• --reporter github / --reporter sarif — emit GitHub Actions annotations or a SARIF 2.1.0 subset for code scanning.
• --probe — include resolved and inventoried workspace member counts when uv or chokkin workspaces are detected.
• --explain / --trace — show why an issue was reported and how reachability was judged. CHK002 explain includes top-level modules and reachable/unreachable import evidence; --trace prints a positive path for reachable files and a negative trace (reason, entry roots, incoming import chain) for unreachable files. These are the intended path for investigating and reporting false positives.

Exit codes are fixed for CI:

0: no reportable issues
1: issues found
2: CLI/config error
3: internal error

Configuration

Zero config is the default. When you need precision, configure [tool.chokkin] in pyproject.toml (standalone chokkin.toml / .chokkin.toml are also accepted). chokkin --init appends a starter [tool.chokkin] reflecting what auto-discovery found.

[tool.chokkin]
entry = [
  "src/acme/__main__.py",
  "src/acme/asgi.py:application",
  "manage.py",
]
project = [
  "src/**/*.py",
  "tests/**/*.py",
  "scripts/**/*.py",
]
mode = "auto"             # auto | app | library
production = false
target_version = "py311"  # Python version of the analyzed project
respect_gitignore = true
confidence = "likely"     # certain | likely | maybe
exclude = [
  ".venv/**",
  ".chokkin/**",
  "build/**",
  "dist/**",
  "**/__pycache__/**",
]
vendored = [             # analyzed and traced, but never reported
  "**/_vendor/**",
  "**/vendored/**",
  "**/externals/**",
  "**/third_party/**",
]

[tool.chokkin.dependencies]
dev_groups = ["dev", "test", "tests", "lint", "docs"]
runtime_groups = ["server", "worker"]
type_groups = ["types", "typing", "mypy"]

# distribution name -> import name(s), for cases the bundled map doesn't cover
[tool.chokkin.package_module_map]
"PyYAML" = ["yaml"]
"Pillow" = ["PIL"]
"protobuf" = ["google.protobuf"]  # dotted names pick one distribution under a namespace package

# CLI name -> distribution name, used by CHK008/CHK002 binary-usage checks
[tool.chokkin.binary_map]
"sphinx-build" = "Sphinx"

[tool.chokkin.plugins]
pytest = true
django = true
fastapi = true

# Per-rule severity overrides (off / info / warning / error)
[tool.chokkin.severity]
CHK001 = "off"
CHK006 = "info"
CHK002 = "error"

The root .chokkin/ directory is reserved for analyzer data and is always excluded, even with custom excludes. Keep analyzed source files outside it.

Modes

mode = "auto" picks one of:

• app mode — there's a clear entry (console_scripts, manage.py, asgi.py, wsgi.py, app.py). Unused files are reported aggressively.
• library mode — a [project] name with a package and no clear entry. Public modules may be imported by external users, so unused files/exports are reported at low confidence (or as info). For serious unused-file detection in a library, declare entry explicitly.
• workspace mode — multiple pyproject.toml files or tool.uv.workspace.members. Each member is analyzed separately (per-member [tool.chokkin.workspaces.<name>] config is supported), sharing the workspace lockfile. Without a workspace declaration (llama_index-style monorepos), nested pyproject.toml files up to four directories deep that declare a [project] name become members automatically; hidden, build, and test directories and exclude globs are skipped, a warning reports the member count, and --no-auto-workspace turns this off. A member (declared or detected) that names a distribution and has no app entry is scored like a library: its unreachable files drop to maybe and its tests are not reported, except files its own wheel targets leave out (such as docs/conf.py), which keep app scoring.

Dependency contexts

Dependencies and files are both assigned contexts (runtime / dev / test / docs / lint / type / optional extras). That's what powers CHK005: import pytest in tests/ with pytest in your dev group is fine; the same import in src/ is a misplaced dependency. Default CHK003 reporting focuses on runtime imports; --strict also reports undeclared type/test/docs/dev imports. TYPE_CHECKING-only imports (including typing aliases) are type-context, while try: import orjson / except ImportError and platform-guarded imports remain informational conditional candidates when undeclared.

Plugins

Frameworks reference modules through strings and decorators, which pure import analysis can't see. Plugins close that gap by adding entry files, string/module references, and binary usage:

• v0.1: pytest, django, fastapi/uvicorn
• v0.2+: tox/nox/pre-commit/GitHub Actions binary usage detection, static Flask/Celery route/task references, conventional Sphinx/MkDocs/Alembic config entries, and .ipynb code-cell parsing.

For example, the Django plugin treats INSTALLED_APPS / MIDDLEWARE / ROOT_URLCONF strings as module references and migrations/** as framework-used. Route handlers decorated with @router.get / @router.websocket etc. are treated as externally used.

Suppressing issues

Inline and file-level ignores:

from legacy import old_api  # chokkin: ignore[CHK003]

# chokkin: file-ignore[CHK006]   (at the top of a file)

Config ignores, keyed by rule code (globs over distribution names, paths, or path:symbol):

[tool.chokkin.ignore]
CHK001 = ["src/acme/generated/**/*.py"]
CHK002 = ["boto3", "google-cloud-*"]
CHK006 = ["src/acme/public_api.py:*"]

For large existing projects, a baseline freezes current issues so CI only fails on new ones:

uvx chokkin --baseline chokkin-baseline.json --update-baseline
uvx chokkin --baseline chokkin-baseline.json

Baseline and --reporter json output include schema_version: "1". v0.2 baseline files without that field remain readable. Published JSON Schema files live under docs/schema/; migration notes are in docs/dev/schema-migration-notes.md.

CI adoption

For an existing project, generate and review the baseline once:

uvx chokkin --baseline chokkin-baseline.json --update-baseline
git add chokkin-baseline.json

Then wire the baseline into pull request checks with the bundled GitHub Action. It emits GitHub annotations, writes SARIF for code scanning, and fails only for findings not already present in the baseline:

name: chokkin

on:
  pull_request:

permissions:
  contents: read
  security-events: write

jobs:
  chokkin:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: watany-dev/chokkin@9341c0b9d678b39b075df0eea440dbc87a1b605a # v0.6.0
        with:
          baseline: chokkin-baseline.json
          sarif-file: chokkin.sarif
      - uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
        if: always()
        with:
          sarif_file: chokkin.sarif

Pin the action to a full commit SHA with the tag as a comment, as above: a tag can be moved, a SHA cannot, and Dependabot still bumps both.

Without the action, pin the version with uvx:

      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
      - run: uvx chokkin@0.7.2 --baseline chokkin-baseline.json --reporter github

Installation

chokkin is a single Rust binary shipped inside a Python wheel (prebuilt for Linux/macOS/Windows), so all of these work without a Rust toolchain:

uvx chokkin        # run without installing
pipx run chokkin
pip install chokkin

chokkin never executes your project's code — analysis is fully static. It also doesn't require your project's virtualenv: if .venv exists it is read for dist-info metadata (METADATA, top_level.txt, RECORD, entry_points.txt), otherwise manifests, lockfiles, and bundled maps are used.

Contributing

See CONTRIBUTING.md. The full design specification (analysis engine, import resolution strategy, roadmap) is in docs/dev/spec.ja.md (Japanese).

The pipeline benchmark covers full cold/warm analysis, disk parse caching, reachability caching, and discovery after cache population with ~2 KiB modules. Run cargo bench --bench pipeline; set CHOKKIN_BENCH_LARGE=1 to add 5k/10k to the default 1k case.

License

MIT