pipdeptree

pipdeptree is a command-line utility that renders the packages installed in a Python environment as a hierarchical dependency tree. Where pip freeze produces a flat list, pipdeptree shows which packages are top-level and which are pulled in as transitive dependencies, and it surfaces version conflicts and circular dependencies that would otherwise stay hidden.

Beyond the default tree, it can reverse the graph to explain why a given package is installed, resolve requirements against a package index without installing them, read a PEP 751 lock file offline, and emit output as JSON, Mermaid, or Graphviz for documentation and tooling pipelines.

What You Get

• A pipdeptree CLI that prints installed packages as a dependency tree with required and installed version constraints
• Reverse-tree mode (--reverse) that explains why a package is present by tracing which parents depend on it
• Multiple output renderers: plain text, JSON, freeze-style, Mermaid, and Graphviz (SVG/DOT)
• Conflict and circular-dependency detection that warns when installed versions violate declared requirements
• Offline and index-based inspection via from-lock (PEP 751) and from-index subcommands, plus a --summary environment health report

Common Use Cases

• Debugging why an unexpected package or version ended up in a virtualenv
• Auditing an environment for version conflicts and circular dependencies before shipping
• Generating dependency graphs (Mermaid/Graphviz) for documentation or architecture reviews

Under The Hood

Architecture — pipdeptree is organized under src/pipdeptree/ around a small model-and-render core. _models/package.py and _models/dag.py build a directed acyclic graph of distributions from installed metadata, _discovery.py and _detect_env.py locate the active environment, and a pluggable _render/ package (text, json, json_tree, mermaid, graphviz, freeze, rich_text, summary) turns the graph into each output format. Subcommand entry points _from_index.py and _from_lock.py add index-resolution and PEP 751 lock parsing, all wired through _cli.py.

Tech Stack — Pure Python (requires a recent Python), packaged with a modern pyproject.toml. Runtime dependencies are minimal: packaging for version handling plus tomli on older interpreters. Optional extras pull in graphviz, rich, and index-resolution helpers only when those features are used. Tooling includes tox, pytest with coverage, and Sphinx docs.

Code Quality — The codebase is cleanly modularized into private _-prefixed modules with a dedicated tests/ suite covering models, parsers, CLI, and each renderer (test_api, test_cli, test_computed, plus render/ tests), backed by pytest, pytest-mock, and coverage defaults. Small single-responsibility modules and typed helpers keep the graph and rendering logic readable.

API Design — As a CLI-first tool the developer experience centers on ergonomic flags and subcommands (--reverse, --packages, -o <format>, from-index, from-lock, --summary) with short aliases, backed by readthedocs documentation and copy-pasteable README examples, so common tasks require no configuration.