pipdeptree Documentation

Beyond simple tree visualization, pipdeptree provides the following features:

• Detect conflicting dependencies: Identifies packages required at incompatible versions by different parent packages.
• Find circular dependencies: Detects cycles within the dependency graph.
• Reverse lookup: Determine why a specific package is installed using the --reverse --packages <name> flags.
• Export formats: Export the dependency graph to JSON, Mermaid diagrams, or Graphviz graphs for external analysis.

To set up a development environment, clone the repository and use tox to install pipdeptree in editable mode along with its test dependencies.

Note: The build uses Meson for editable installs and wheels. The native target invokes Cargo for dependency resolution and compilation via PyO3. Rust handles environment inspection, package data, dependency graphs, lock/index input, and rendering, while Python exposes the public API, notebook display hooks, and CLI output.

git clone https://github.com/tox-dev/pipdeptree.git
cd pipdeptree
tox run -e dev

Use the --python auto flag to force pipdeptree to require an active virtual environment. If no virtual environment is detected, the command will fail.

$ pipdeptree --python auto

You can pass PEP 508 requirement strings directly as positional arguments. This includes version specifiers, extras, and environment markers.

• Extras: Use name[extra] syntax. The resolver pulls extra dependencies into the tree.
• Environment Markers: Use markers like python_version >= "3.10". Note: You must quote the argument in your shell to ensure the marker is passed correctly.
• Multiple Requirements: Passing multiple requirements resolves them into a single combined graph.

Testing is split between Rust and Python suites:

1. Rust tests: Tests the production code through the Application boundary. Use cargo test or cargo llvm-cov for coverage.
2. Python tests: Tests the packaged API and CLI. You can run these via tox using supported Python versions from 3.10 through 3.14.

To run the Rust public API tests with coverage requirements:

cargo test --no-default-features --test public_api
cargo llvm-cov --no-default-features --test public_api --fail-under-lines 100 --fail-under-functions 100
tox run -e 3.14

Execute type checking via the type tox environment.

tox run -e type

If you change code that alters the rendered output in the documentation, you must refresh the pinned blocks and review the diff using the docs-update tox environment.

tox run -e docs-update

Use cargo fmt and cargo clippy for Rust code. To run the full suite of repository hooks (including Ruff, TOML formatters, workflow validation, and Prettier), use the fix tox environment.

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
tox run -e fix

To inspect the dependencies of a specific Python interpreter regardless of which virtual environment is currently active, use the --python flag followed by the path to that interpreter's executable.

$ pipdeptree --python /path/to/venv/bin/python

By default, pipdeptree auto-detects your active virtual environment (such as venv, virtualenv, conda, or poetry) and inspects its installed packages. If no virtual environment is active, it falls back to inspecting the packages of the interpreter currently running pipdeptree (e.g., system packages if installed globally).

$ pipdeptree

You can build packages using the PEP 517 Meson backend with uv build. To inspect the native build without creating a wheel, use meson directly to setup and compile the build directory.

# Build via PEP 517
uv build

# Inspect native build without creating a wheel
meson setup build
meson compile -C build