import-cruiser

Analyze, validate, and visualize Python import dependencies.

import-cruiser helps you quickly answer:

• Where are tight couplings?
• Are there circular imports?
• Are architecture rules respected?

Why teams use it

• Fast graph export to html, svg, and dot
• Rule-based validation for CI (validate --strict)
• Readable interactive HTML output for architecture reviews
• Works out of the box on regular Python codebases

See it in action: project self-graph

Dependency graph of src/import_cruiser, generated by the tool itself:

Run make self-graph to refresh these artifacts—the script passes --show-loc so clusters include LOC badges in the DOT/HTML/SVG exports (with --cluster-mode module --cluster-depth 1, the self-graph renders a single top-level import_cruiser cluster and skips the src path layer). The target also passes --include-external-deps, so non-dev third-party packages render as a grouped green block labeled “External dependencies” (without LOC badges). External roots are read from both tool.poetry.dependencies and project.dependencies.

Install

pip install import-cruiser

60-second quick start

From your repo root:

# 1) Generate an interactive dependency graph
import-cruiser export . --format html --output deps.html

# 2) Generate an embeddable SVG
import-cruiser export . --format svg --output deps.svg

# 3) Detect cycles and get a JSON report
import-cruiser analyze . --output report.json

For larger repos, filter noise:

import-cruiser export . \
  --format html \
  --include-path '^src/' \
  --exclude-common-noise-paths \
  --output deps-src.html

Commands

import-cruiser analyze  <path>   # analyze imports, output json/dot/svg/html
import-cruiser export   <path>   # export graph dot/svg/html
import-cruiser validate <path>   # enforce dependency rules

Most useful options

• --format {json,dot,svg,html}
• --include, --exclude
• --include-path, --exclude-path
• --exclude-common-noise-paths
• --cluster-depth, --cluster-mode
• --include-db-connectors, --include-http-hosts
• --show-loc to show LOC per node/cluster and total LOC badge in HTML
• --include-external-deps to surface non-dev third-party packages as grouped green nodes (auto-enabled in the self-graph)
• --external-deps-include, --external-deps-exclude to filter which external dependency roots are surfaced

Validate architecture in CI

Minimal import-cruiser.json example:

{
  "rules": [
    {
      "name": "no-data-to-ui",
      "severity": "error",
      "from": { "path": "\\.data" },
      "to": { "path": "\\.ui" },
      "allow": false
    }
  ]
}

Run in CI:

import-cruiser validate . --config import-cruiser.json --strict --output-format github

Development

poetry install
poetry run pytest

License

MIT