CLI reference

Dependency tree of the installed python packages

pipdeptree [-h] [-w {silence,suppress,fail}] [-p P] [-e P] [--exclude-dependencies]
           [-x [{none,explicit,active}]] [-f] [--encoding E] [-a] [-d D] [-r] [--summary]
           [-j | --json-tree | --mermaid | --graph-output FMT | -o FMT] [-v]
           [--python PYTHON] [--path PATH] [-l | -u] [--license] [-m M] [-c C]
           {from-index,i,from-lock,l} ...

pipdeptree options

  • -h, --help - show this help message and exit

  • -w WARN, --warn WARN - warning control: suppress will show warnings but return 0 whether or not they are present; silence will not show warnings at all and always return 0; fail will show warnings and return 1 if any are present (default: suppress)

  • -p P, --packages P - comma separated list of packages to show - wildcards are supported, like 'somepackage.*'. append an extras spec to also show a package’s extra dependencies, like somepackage[extra1,extra2]

  • -e P, --exclude P - comma separated list of packages to not show - wildcards are supported, like 'somepackage.*'. (cannot combine with -p or -a)

  • --exclude-dependencies - used along with –exclude to also exclude dependencies of packages

  • -x EXTRAS, --extras EXTRAS - which optional (extras) dependencies to include: 'explicit' (default) shows extras requested via name[extra], including transitively; 'active' also shows extras whose dependencies are all installed; 'none' shows none. Bare –extras means 'explicit' (default: explicit)

  • -f, --freeze - (Deprecated, use -o) print names so as to write freeze files

  • --encoding E - the encoding to use when writing to the output (default: utf-8)

  • -a, --all - list all deps at top level (text, rich, and freeze render only)

  • -d D, --depth D - limit the depth of the tree (text, rich, freeze, and graphviz render only) (default: inf)

  • -r, --reverse - render the dependency tree in the reverse fashion ie. the sub-dependencies are listed with the list of packages that need them under them

  • --summary - render a one-block health report of the tree instead of the tree itself; combine with -o text (default), rich, or json. Composes with from-index/from-lock

  • -j, --json - (Deprecated, use -o) raw JSON - this will yield output that may be used by external tools

  • --json-tree - (Deprecated, use -o) nested JSON - mimics the text format layout

  • --mermaid - (Deprecated, use -o) https://mermaid.js.org flow diagram

  • --graph-output FMT - (Deprecated, use -o) Graphviz rendering with the value being the graphviz output e.g.: dot, jpeg, pdf, png, svg

  • -o FMT, --output FMT - specify how to render the tree; supported formats: freeze, json, json-tree, mermaid, rich, text, or graphviz-* (e.g. graphviz-png, graphviz-dot) (default: text)

  • -v, --version - show program’s version number and exit

  • --license - (Deprecated, use –metadata license) list the license(s) of a package

  • -m M, --metadata M - comma separated list of metadata fields to display from the package METADATA file (e.g. license,summary,author,home-page,requires-python) (default: )

  • -c C, --computed C - comma separated list of computed fields to display: size, size-raw, unique-deps-count, unique-deps-names, unique-deps-size (default: )

pipdeptree select

choose what to render

  • --python PYTHON - Python interpreter to inspect. By default it auto-detects your active virtual environment (venv, virtualenv, conda, or poetry), falling back to the interpreter running pipdeptree when none is found. With "auto" it detects the active virtual environment and fails if it can’t.

  • --path PATH - passes a path used to restrict where packages should be looked for (can be used multiple times)

  • -l, --local-only - if in a virtualenv that has global access do not show globally installed packages

  • -u, --user-only - only show installations in the user site dir

pipdeptree from-index (i)

Resolve the given requirements by querying the package index (PyPI) and render the dependency tree without installing or inspecting the environment. Positional arguments are inline PEP 508 requirements; files are supplied explicitly via –requirements and –pyproject. A lone –pyproject is resolved natively (honoring [tool.nab]); otherwise every source merges into one resolve. Needs the optional index resolver (pip install pipdeptree[index]).

pipdeptree from-index [-h] [-w {silence,suppress,fail}] [-p P] [-e P]
                      [--exclude-dependencies] [-x [{none,explicit,active}]] [-f]
                      [--encoding E] [-a] [-d D] [-r] [--summary] [-j | --json-tree |
                      --mermaid | --graph-output FMT | -o FMT] [--requirements FILE]
                      [--pyproject FILE] [--index-url URL] [--extra-index-url URL]
                      [REQUIREMENT ...]

pipdeptree from-index positional arguments

  • REQUIREMENT - inline PEP 508 requirement to resolve, like a pip install argument; repeatable

pipdeptree from-index options

  • -h, --help - show this help message and exit

  • -w WARN, --warn WARN - warning control: suppress will show warnings but return 0 whether or not they are present; silence will not show warnings at all and always return 0; fail will show warnings and return 1 if any are present (default: suppress)

  • -p P, --packages P - comma separated list of packages to show - wildcards are supported, like 'somepackage.*'. append an extras spec to also show a package’s extra dependencies, like somepackage[extra1,extra2]

  • -e P, --exclude P - comma separated list of packages to not show - wildcards are supported, like 'somepackage.*'. (cannot combine with -p or -a)

  • --exclude-dependencies - used along with –exclude to also exclude dependencies of packages

  • -x EXTRAS, --extras EXTRAS - which optional (extras) dependencies to include: 'explicit' (default) shows extras requested via name[extra], including transitively; 'active' also shows extras whose dependencies are all installed; 'none' shows none. Bare –extras means 'explicit' (default: explicit)

  • -f, --freeze - (Deprecated, use -o) print names so as to write freeze files

  • --encoding E - the encoding to use when writing to the output (default: utf-8)

  • -a, --all - list all deps at top level (text, rich, and freeze render only)

  • -d D, --depth D - limit the depth of the tree (text, rich, freeze, and graphviz render only) (default: inf)

  • -r, --reverse - render the dependency tree in the reverse fashion ie. the sub-dependencies are listed with the list of packages that need them under them

  • --summary - render a one-block health report of the tree instead of the tree itself; combine with -o text (default), rich, or json. Composes with from-index/from-lock

  • -j, --json - (Deprecated, use -o) raw JSON - this will yield output that may be used by external tools

  • --json-tree - (Deprecated, use -o) nested JSON - mimics the text format layout

  • --mermaid - (Deprecated, use -o) https://mermaid.js.org flow diagram

  • --graph-output FMT - (Deprecated, use -o) Graphviz rendering with the value being the graphviz output e.g.: dot, jpeg, pdf, png, svg

  • -o FMT, --output FMT - specify how to render the tree; supported formats: freeze, json, json-tree, mermaid, rich, text, or graphviz-* (e.g. graphviz-png, graphviz-dot) (default: text)

  • --requirements FILE - a requirements.txt or .in style file (nested -r, -c constraints, markers and comments supported); repeatable

  • --pyproject FILE - a pyproject.toml handed natively to the resolver when it is the only source; repeatable

  • --index-url URL - primary package index to resolve against, replacing PyPI; falls back to PIP_INDEX_URL then UV_INDEX_URL when unset, and defaults to PyPI

  • --extra-index-url URL - additional package index to resolve against, repeatable; falls back to PIP_EXTRA_INDEX_URL then UV_EXTRA_INDEX_URL (whitespace separated) when unset

pipdeptree from-lock (l)

Read a PEP 751 lock file (pylock.toml) and render its dependency tree. The lock is already resolved, so this is fully offline – no package index, network, or extra is required.

pipdeptree from-lock [-h] [-w {silence,suppress,fail}] [-p P] [-e P] [--exclude-dependencies]
                     [-x [{none,explicit,active}]] [-f] [--encoding E] [-a] [-d D] [-r]
                     [--summary] [-j | --json-tree | --mermaid | --graph-output FMT | -o FMT]
                     PYLOCK

pipdeptree from-lock positional arguments

  • PYLOCK - path to a PEP 751 pylock.toml lock file

pipdeptree from-lock options

  • -h, --help - show this help message and exit

  • -w WARN, --warn WARN - warning control: suppress will show warnings but return 0 whether or not they are present; silence will not show warnings at all and always return 0; fail will show warnings and return 1 if any are present (default: suppress)

  • -p P, --packages P - comma separated list of packages to show - wildcards are supported, like 'somepackage.*'. append an extras spec to also show a package’s extra dependencies, like somepackage[extra1,extra2]

  • -e P, --exclude P - comma separated list of packages to not show - wildcards are supported, like 'somepackage.*'. (cannot combine with -p or -a)

  • --exclude-dependencies - used along with –exclude to also exclude dependencies of packages

  • -x EXTRAS, --extras EXTRAS - which optional (extras) dependencies to include: 'explicit' (default) shows extras requested via name[extra], including transitively; 'active' also shows extras whose dependencies are all installed; 'none' shows none. Bare –extras means 'explicit' (default: explicit)

  • -f, --freeze - (Deprecated, use -o) print names so as to write freeze files

  • --encoding E - the encoding to use when writing to the output (default: utf-8)

  • -a, --all - list all deps at top level (text, rich, and freeze render only)

  • -d D, --depth D - limit the depth of the tree (text, rich, freeze, and graphviz render only) (default: inf)

  • -r, --reverse - render the dependency tree in the reverse fashion ie. the sub-dependencies are listed with the list of packages that need them under them

  • --summary - render a one-block health report of the tree instead of the tree itself; combine with -o text (default), rich, or json. Composes with from-index/from-lock

  • -j, --json - (Deprecated, use -o) raw JSON - this will yield output that may be used by external tools

  • --json-tree - (Deprecated, use -o) nested JSON - mimics the text format layout

  • --mermaid - (Deprecated, use -o) https://mermaid.js.org flow diagram

  • --graph-output FMT - (Deprecated, use -o) Graphviz rendering with the value being the graphviz output e.g.: dot, jpeg, pdf, png, svg

  • -o FMT, --output FMT - specify how to render the tree; supported formats: freeze, json, json-tree, mermaid, rich, text, or graphviz-* (e.g. graphviz-png, graphviz-dot) (default: text)

Summary metrics

Fields emitted by --summary (styled with -o text, rich or json). The Modes column notes where each is available: all works for every command; default needs an installed environment and is reported as n/a (omitted in JSON) under from-index/from-lock.

Field

Meaning

Modes

total_packages

Number of packages in the tree.

all

direct_dependencies

Top-level packages (not required by any other package).

all

transitive_dependencies

Packages pulled in only as a dependency of another (total - direct).

all

max_depth

Longest dependency chain, counted in packages.

all

cyclic_dependencies

Number of dependency cycles detected.

all

missing_dependencies

Distinct packages required but not installed.

default

conflicting_dependencies

packages with an unsatisfied requirement and the total conflicting edges.

default

licenses

breakdown per license string, count of unknown licenses, and a copyleft flag.

default

min_requires_python

Highest Requires-Python lower bound across packages (the effective floor).

default

total_size / total_size_raw

On-disk size of all packages, human-readable and in bytes.

default