Usage patterns

Running in virtualenvs

By default pipdeptree inspects your active virtual environment (venv, virtualenv or conda). With none active, it asks Poetry for the environment of the project in the working directory, and falls back to the interpreter running pipdeptree when that fails too. A system installation therefore inspects the system packages:

$ pipdeptree

To inspect a specific interpreter regardless of what is active, pass its path to --python:

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

Use --python auto to require an active virtual environment. The command fails when it cannot find one:

$ pipdeptree --python auto

Installing pipdeptree inside the virtual environment and running it there gives the same result.

pipdeptree ignores a Poetry environment inside the project it runs in, such as an in-project .venv, because a repository can commit one and pipdeptree runs nothing from the working directory unless you name it. To inspect that environment, activate it or pass its interpreter.

$ pipdeptree --python .venv/bin/python

from-index (resolve by querying the index)

pipdeptree inspects an installed environment by default. The from-index subcommand queries a package index and returns the resolved tree before installation.

Positional arguments are PEP 508 requirements or local source paths, the same strings you pass to pip install. You supply files with repeatable flags:

  • positional REQUIREMENT – an inline PEP 508 requirement string, version specifiers and extras included;

  • --requirements FILE – a standard requirements.txt or .in style file;

  • --pyproject FILE – a pyproject.toml handed to the resolver, which reads [project].dependencies and honors its [tool.nab] configuration.

Pass at least one source. Each edge shows the range its parent requires and the candidate version the resolver selected, for example [required: <5,>=4, candidate: 4.15.1]. An unrestricted dependency reads required: Any. A package may appear more than once under the same parent when several active requirements declare it. --json and --json-tree include each requirement’s marker and extra information in a declaration object. These values come from the selected resolve, not packages installed on your machine.

Nab caches index responses and package metadata for repeat runs. from-index uses NAB_CACHE_DIR when set, then $XDG_CACHE_HOME/nab or ~/.cache/nab. A relative XDG_CACHE_HOME is ignored. Set NAB_CACHE_DIR to keep the cache elsewhere.

Nab logs a warning when it skips a release, for example one whose metadata does not parse. pipdeptree prints these in its own warning block, hides them with --warn silence, and replaces their control characters with U+FFFD as it does for package strings. They do not make --warn fail exit 1.

Resolve inline requirements

A single requirement resolves to its full tree:

$ pipdeptree from-index "starlette"
starlette==1.6.0
└── anyio [required: <5,>=3.6.2, candidate: 4.15.1]
    ├── idna [required: >=2.8, candidate: 3.19]
    └── typing-extensions [required: >=4.16.0, candidate: 4.16.0]

Several requirements resolve together into one graph, and a version specifier bounds the pick:

$ pipdeptree from-index "fastapi<=0.115.2" starlette
fastapi==0.115.2
...
├── starlette [required: <0.41.0,>=0.37.2, candidate: 0.40.0]
...

Request extras with the name[extra] syntax. The resolver pulls the extra’s dependencies into the tree. The extra: socks label on pysocks shows why that dependency is active:

$ pipdeptree from-index "requests[socks]"
requests==2.34.2
...
├── pysocks [required: !=1.5.7,>=1.5.6, candidate: 1.7.1, extra: socks]
...

An environment marker gates a requirement on the interpreter that the resolve targets. A matching marker includes the requirement; a non-matching marker drops it. Quote the argument so the shell keeps the marker attached:

$ pipdeptree from-index 'idna; python_version >= "3.10"'
idna==3.19

Resolve from a requirements file

Point --requirements at a requirements.txt:

$ pipdeptree from-index --requirements requirements.txt

pipdeptree parses the file as a standard requirements file, so a real-world one resolves as-is. Take this requirements.txt:

-r base.txt                        # nested include, followed
-c constraints.txt                 # constraints, fed to the resolver
httpx[http2]                       # extras kept
tomli; python_version < "3.11"     # environment marker kept
# pin chosen by the security team   <- comment, ignored
requests==2.32.3 \
    --hash=sha256:0000000000000000000000000000000000000000000000000000000000000000

Each directive maps as follows: the -r base.txt include is read inline, the -c constraints.txt pins bound the resolve, the marker and the [http2] extra reach the resolver intact, the comment drops out, and the --hash line resolves requests while pipdeptree ignores the hash (the resolver verifies nothing from the index). The same applies to --index-url and other pip-specific options. The resolve takes its indexes from the command line and the environment only (see below), so an -i, --index-url or --extra-index-url line prints a warning with the file and line number; --warn fail turns it into exit code 1.

Resolve from a pyproject.toml

With --pyproject as the sole source, the resolver receives the full [project] table and the file’s [tool.nab] configuration:

$ pipdeptree from-index --pyproject pyproject.toml

Add any other source and the [project].dependencies from that pyproject merge into one combined resolve instead. Its [tool.nab] settings drop out on this path:

$ pipdeptree from-index --pyproject pyproject.toml httpx

Combine and repeat sources

Both flags repeat. The resolver merges their sources with the positional requirements:

$ pipdeptree from-index --requirements a.txt --requirements b.txt --pyproject p.toml extra-pkg

Use a private or custom index

By default the resolve runs against PyPI. Point it at an internal index with --index-url and add more with --extra-index-url (repeatable):

$ pipdeptree from-index "internal-lib" --index-url https://nexus.corp/repository/pypi/simple
$ pipdeptree from-index "internal-lib" --extra-index-url https://nexus.corp/repository/pypi/simple

--index-url replaces PyPI as the primary index, matching pip’s --index-url. --extra-index-url keeps PyPI as the primary and appends each extra after it. When a flag is absent, the value falls back to the environment: --index-url reads PIP_INDEX_URL then UV_INDEX_URL, and --extra-index-url reads PIP_EXTRA_INDEX_URL then UV_EXTRA_INDEX_URL (both whitespace separated, like pip and uv). An empty variable counts as unset. With nothing set the resolve uses PyPI. pipdeptree drops a user name and password from these URLs before the resolve. Nab sends no credentials, so an index that requires authentication does not work with from-index.

The resolver searches indexes in order and uses the first index that contains a package. pip merges index results and picks the highest version. Put the trusted index for each package first.

The index flags and their environment fallbacks override a --pyproject’s own [tool.nab].indexes. With no flag and no environment override, the resolve uses the indexes declared in the pyproject.

$ PIP_INDEX_URL=https://nexus.corp/repository/pypi/simple pipdeptree from-index "internal-lib"
$ pipdeptree from-index --pyproject pyproject.toml --index-url https://nexus.corp/repository/pypi/simple

Apply render flags

The graph and render flags behave as they do for the default command. Emit JSON for tooling:

$ pipdeptree from-index "starlette" -o json
[
    ...
                "key": "anyio",
                "package_name": "anyio",
                "candidate_version": "4.15.1",
                "required_version": "<5,>=3.6.2",
                "declaration": {
                    "requirement_text": "anyio<5,>=3.6.2",
                    "dependency_specifier": "<5,>=3.6.2",
                    "requirement_condition": null,
                    "dependency_extras": [],
                    "required_for_parent_extras": [],
                    "required_without_parent_extras": true
                }
    ...
]

To inspect Nab’s declaration fields for an edge, select it from flat JSON:

$ pipdeptree -o json from-index 'requests[socks]' | jq '.[]|.dependencies[]|select(.key == "pysocks")|.declaration'
{
  "requirement_text": "PySocks!=1.5.7,>=1.5.6; extra == \"socks\"",
  "dependency_specifier": "!=1.5.7,>=1.5.6",
  "requirement_condition": "extra == \"socks\"",
  "dependency_extras": [],
  "required_for_parent_extras": [
    "socks"
  ],
  "required_without_parent_extras": false
}

requirement_condition retains the marker. dependency_extras lists extras requested on the child; required_for_parent_extras lists parent extras that activate the edge. required_without_parent_extras says whether the parent also requires the child without an extra. --output json-tree exposes the same declaration on each nested dependency. The surrounding JSON identifies the parent and child and shows candidate_version and required_version.

Trace why the resolver pulled a package in with --reverse (-r):

$ pipdeptree from-index "fastapi<=0.115.2" --reverse --packages anyio
anyio==4.15.1
└── starlette==0.40.0 [requires: anyio<5,>=3.6.2]
    └── fastapi==0.115.2 [requires: starlette<0.41.0,>=0.37.2]

Other supported flags include -o mermaid, the graphviz-* formats, --depth (-d), package filters, --extras (-x) and --encoding:

$ pipdeptree from-index "fastapi<=0.115.2" --depth 1
$ pipdeptree from-index "fastapi<=0.115.2" -o mermaid
$ pipdeptree from-index "fastapi<=0.115.2" --packages starlette
$ pipdeptree from-index "fastapi<=0.115.2" --exclude anyio
$ pipdeptree from-index "requests[socks]" --extras none

Resolve editable, local and git requirements

For a requirement that points at a checkout instead of the index, the resolver reads the target’s PEP 621 metadata. Static [project] data needs no build. A project that declares dynamic dependencies triggers its build backend.

Editable installs are a --requirements file directive, so pass them through a file:

$ printf -- '-e ./mypkg\n' > requirements.txt
$ pipdeptree from-index --requirements requirements.txt

Local paths (./mypkg, /abs/path, file:///abs/path, and on Windows .\mypkg or C:\abs\path) work the same, as positional arguments or file lines. A relative file: URL such as file:mypkg or file:./mypkg resolves against the working directory, as pip does, even in a requirements file. A plain ./mypkg line in a requirements file resolves against that file’s directory, where pip uses the working directory. For a pinned git requirement, the resolver clones the repo to its cache and reads the metadata:

$ pipdeptree from-index "mypkg @ git+https://github.com/o/r.git@<full-40-char-commit-sha>"

The git ref must be a full 40-character commit sha; pipdeptree refuses a tag or branch so the resolve stays reproducible. Bare wheel/sdist archive URLs and non-git VCS schemes (hg+/bzr+/svn+) stay out of scope.

Handle errors

A --requirements or --pyproject file must exist; a missing one stops the command. Positional arguments accept requirement strings. Use the file flags for paths:

$ pipdeptree from-index --requirements missing.txt
source file does not exist: missing.txt

A bare wheel/sdist archive URL or a non-git VCS scheme (hg+/bzr+/svn+) has no index mapping:

requirements.txt
foo @ https://h/foo-1.0-py3-none-any.whl
$ pipdeptree from-index --requirements requirements.txt
URL requirements are not supported by the index resolver: foo @ https://h/foo-1.0-py3-none-any.whl

An unpinned git ref fails the same way, and so does a constraint that carries extras or names a source: a URL, a local path or an -e line.

The resolver can pin a package whose name or version is longer than 255 bytes. pipdeptree stops with an error such as package 'version' is longer than 255 bytes instead of rendering it.

The installed-environment display options inspect on-disk files, so from-index does not accept them:

$ pipdeptree from-index "starlette" --metadata license
error: unexpected argument '--metadata' found
...

The same holds for --computed (-c), --license and the environment-inspection options (--python, --path, -l/-u). from-index has neither package files nor an environment to read. No source is an error:

$ pipdeptree from-index
pipdeptree: error: from-index needs at least one REQUIREMENT, --requirements FILE, or --pyproject FILE

from-lock (render a PEP 751 lock)

The from-lock subcommand reads a PEP 751 lock file (pylock.toml) and renders its dependency tree. A lock records the pinned packages, their versions and the edges between them. from-lock runs offline with no package index or network on Python 3.11 through 3.15. The native extension parses TOML with Rust’s toml crate. Take this lock:

pylock.toml
lock-version = "1.0"

[[packages]]
name = "build"
version = "1.5.0"
dependencies = [{ name = "packaging" }, { name = "pyproject-hooks" }]

[[packages]]
name = "packaging"
version = "26.2"

[[packages]]
name = "pyproject-hooks"
version = "1.2.0"
$ pipdeptree from-lock pylock.toml
build==1.5.0
├── packaging [candidate: 26.2]
└── pyproject-hooks [candidate: 1.2.0]

Each edge shows the candidate: version the lock pinned, not a package on your machine. pipdeptree does not inspect an installed environment or install anything.

Producing a pylock.toml

PEP 751 emitters write files that from-lock can read. uv exports one from a project:

$ uv export -o pylock.toml          # or: uv lock then export
$ pipdeptree from-lock pylock.toml

Render flags on a lock

The lock supplies names, versions and edges, so the graph and render flags behave as they do for the default command. Use --packages (-p), --exclude (-e), --depth (-d), --extras (-x), --reverse (-r), --encoding or an output format from -o.

Emit JSON for another tool to consume:

$ pipdeptree from-lock pylock.toml -o json
[
    {
        "package": {
            "key": "build",
            "package_name": "build",
            "candidate_version": "1.5.0"
        },
        "dependencies": [
            {
                "key": "packaging",
                "package_name": "packaging",
                "candidate_version": "26.2"
            },
            {
                "key": "pyproject-hooks",
                "package_name": "pyproject-hooks",
                "candidate_version": "1.2.0"
            }
        ]
    },
    {
        "package": {
            "key": "packaging",
            "package_name": "packaging",
            "candidate_version": "26.2"
        },
        "dependencies": []
    },
    {
        "package": {
            "key": "pyproject-hooks",
            "package_name": "pyproject-hooks",
            "candidate_version": "1.2.0"
        },
        "dependencies": []
    }
]

Flip the edges with --reverse to see which packages pull in a given dependency:

$ pipdeptree from-lock pylock.toml --reverse
packaging==26.2
└── build==1.5.0 [requires: packaging==26.2]
pyproject-hooks==1.2.0
└── build==1.5.0 [requires: pyproject-hooks==1.2.0]

Draw a Mermaid diagram for a docs page or chat client:

$ pipdeptree from-lock pylock.toml -o mermaid

Use the installed-environment filters on lock trees. Keep one root with --packages:

$ pipdeptree from-lock pylock.toml --packages build

Hide a package with --exclude:

$ pipdeptree from-lock pylock.toml --exclude packaging

Stop after the first level with --depth:

$ pipdeptree from-lock pylock.toml --depth 1

Locks without edges

A valid PEP 751 lock may pin packages without recording the edges between them. from-lock then renders a flat list of pinned packages, each with no children:

pylock.toml
lock-version = "1.0"

[[packages]]
name = "build"
version = "1.5.0"

[[packages]]
name = "packaging"
version = "26.2"

[[packages]]
name = "pyproject-hooks"
version = "1.2.0"
$ pipdeptree from-lock pylock.toml
build==1.5.0
packaging==26.2
pyproject-hooks==1.2.0

from-lock does not fill in missing edges from another source; it reads the lock and neither METADATA on disk nor a package index. Without edges the tree, --reverse, --depth, --packages and --exclude act on a graph where each package is a root with no children, and --summary reports zero transitive dependencies and a max depth of one. --freeze output does not change. To see edges, have the lock’s producer record them (uv export does), or render the same packages from an installed environment with the default command or from an index with from-index.

Locks for several environments

A universal lock can pin one package several times, each entry guarded by an environment marker. from-lock evaluates each marker against the interpreter that runs pipdeptree and keeps the entries that match, so one run shows one environment. This lock pins importlib-metadata for interpreters older than Python 3.10:

pylock.toml
lock-version = "1.0"

[[packages]]
name = "build"
version = "1.5.0"
dependencies = [{ name = "importlib-metadata" }]

[[packages]]
name = "importlib-metadata"
version = "8.7.0"
marker = "python_version < '3.10'"

pipdeptree runs on Python 3.11 or newer, so the marker fails, from-lock drops the entry and the edge from build points at nothing; the candidate shows as unknown:

$ pipdeptree from-lock pylock.toml
build==1.5.0
└── importlib-metadata [candidate: ?]

from-lock does not render several targets from one lock at once; run pipdeptree under an interpreter that matches the other environment to project the lock for it.

Lock limitations

A lock carries names, versions and edges, so the installed-environment display options have nothing to read. The subcommand omits them:

$ pipdeptree from-lock pylock.toml --metadata license
error: unexpected argument '--metadata' found
...
$ pipdeptree from-lock pylock.toml --license
error: unexpected argument '--license' found
...

The same holds for --computed (-c) and the environment-inspection options (--python, --path, -l/-u): a lock has no METADATA file, no on-disk sizes and no environment to point at.

A missing lock file stops the command with a message and exit code 1:

$ pipdeptree from-lock missing.toml
lock file does not exist: missing.toml
$ echo $?
1

Malformed TOML returns exit code 1. from-lock also rejects a TOML file with no packages array:

pylock.toml
lock-version = "1.0"
$ pipdeptree from-lock pylock.toml
missing 'packages' array

pipdeptree reports the parse error for an invalid package entry:

pylock.toml
lock-version = "1.0"

[[packages]]
version = "1"
$ pipdeptree from-lock pylock.toml
package is missing 'name'

pipdeptree rejects a package name or version longer than 255 bytes the same way, for example with package 'name' is longer than 255 bytes. It also stops on a package marker longer than 1024 bytes or with more than 16 extra comparisons, and on a dependencies entry whose name is not a project name, such as one that carries a marker, a version specifier or a direct URL.

Filtering packages

By default, pipdeptree shows the full dependency tree of your environment:

$ pipdeptree
covdefaults==2.3.0
└── coverage [required: >=6.0.2, installed: 7.15.1]
cryptography==2.7
diff_cover==10.3.0
├── chardet [required: >=3.0.0, installed: 7.4.3]
├── Jinja2 [required: >=2.7.1, installed: 3.1.6]
│   └── MarkupSafe [required: >=2.0, installed: 3.0.3]
├── pluggy [required: >=0.13.1,<2, installed: 1.6.0]
└── Pygments [required: >=2.19.1,<3.0.0, installed: 2.20.0]
oauthlib==3.0.0
pipdeptree==4.0.0
├── nab-index [required: >=0.0.11, installed: 0.0.14]
│   ├── nab-provider [required: ==0.0.14, installed: 0.0.14]
│   │   ├── nab-resolver [required: ==0.0.14, installed: 0.0.14]
│   │   └── typing_extensions [required: >=4.6, installed: 4.16.0]
│   ├── packaging [required: >=24.0, installed: 26.2]
│   ├── truststore [required: >=0.10, installed: 0.10.4]
│   ├── typing_extensions [required: >=4.6, installed: 4.16.0]
│   └── urllib3 [required: >=2.0, installed: 2.7.0]
└── nab-project [required: >=0.0.14, installed: 0.0.14]
    ├── build [required: >=1.2, installed: 1.5.1]
    │   ├── packaging [required: >=24.0, installed: 26.2]
    │   └── pyproject_hooks [required: Any, installed: 1.2.0]
    ├── installer [required: >=1.0, installed: 1.0.1]
    ├── nab-index [required: ==0.0.14, installed: 0.0.14] (*)
    ├── nab-provider [required: ==0.0.14, installed: 0.0.14] (*)
    ├── nab-resolver [required: ==0.0.14, installed: 0.0.14]
    ├── pyproject_hooks [required: >=1.2, installed: 1.2.0]
    ├── tomli [required: >=2.0, installed: 2.4.1]
    ├── tomli_w [required: >=1.2, installed: 1.2.0]
    └── typing_extensions [required: >=4.6, installed: 4.16.0]
pyjwt==1.7.1
PySocks==1.7.1
pytest-cov==7.1.0
├── coverage [required: >=7.10.6, installed: 7.15.1]
├── pluggy [required: >=1.2, installed: 1.6.0]
└── pytest [required: >=7, installed: 9.1.1]
    ├── iniconfig [required: >=1.0.1, installed: 2.3.0]
    ├── packaging [required: >=22, installed: 26.2]
    ├── pluggy [required: >=1.5,<2, installed: 1.6.0]
    └── Pygments [required: >=2.7.2, installed: 2.20.0]
requests==2.32.3
├── certifi [required: >=2017.4.17, installed: 2024.8.30]
├── charset_normalizer [required: >=2,<4, installed: 3.4.0]
├── idna [required: >=2.5,<4, installed: 3.10]
└── urllib3 [required: >=1.21.1,<3, installed: 2.7.0]

Show selected packages with --packages (-p):

$ pipdeptree --packages pytest
pytest==9.1.1
├── iniconfig [required: >=1.0.1, installed: 2.3.0]
├── packaging [required: >=22, installed: 26.2]
├── pluggy [required: >=1.5,<2, installed: 1.6.0]
└── Pygments [required: >=2.7.2, installed: 2.20.0]

Separate multiple packages with commas. You can use wildcards:

$ pipdeptree --packages 'pytest*'
pytest-cov==7.1.0
├── coverage [required: >=7.10.6, installed: 7.15.1]
├── pluggy [required: >=1.2, installed: 1.6.0]
└── pytest [required: >=7, installed: 9.1.1]
    ├── iniconfig [required: >=1.0.1, installed: 2.3.0]
    ├── packaging [required: >=22, installed: 26.2]
    ├── pluggy [required: >=1.5,<2, installed: 1.6.0]
    └── Pygments [required: >=2.7.2, installed: 2.20.0]

A package entry may carry an extras spec such as somepackage[extra1,extra2] to include its optional dependencies. pipdeptree strips the extras spec before matching the name, so wildcards such as somepackage*[extra1] still work. pipdeptree includes an extra requested through --packages even with --extras none:

$ pipdeptree --packages "requests[socks]" --extras none
requests==2.32.3
├── certifi [required: >=2017.4.17, installed: 2024.8.30]
├── charset_normalizer [required: >=2,<4, installed: 3.4.0]
├── idna [required: >=2.5,<4, installed: 3.10]
├── PySocks [required: >=1.5.6,!=1.5.7, installed: 1.7.1, extra: socks]
└── urllib3 [required: >=1.21.1,<3, installed: 2.7.0]

Excluding packages

Use --exclude (-e) to hide specific packages:

$ pipdeptree --exclude pip,pipdeptree,setuptools,wheel
covdefaults==2.3.0
└── coverage [required: >=6.0.2, installed: 7.15.1]
cryptography==2.7
diff_cover==10.3.0
├── chardet [required: >=3.0.0, installed: 7.4.3]
├── Jinja2 [required: >=2.7.1, installed: 3.1.6]
│   └── MarkupSafe [required: >=2.0, installed: 3.0.3]
├── pluggy [required: >=0.13.1,<2, installed: 1.6.0]
└── Pygments [required: >=2.19.1,<3.0.0, installed: 2.20.0]
nab-project==0.0.14
├── build [required: >=1.2, installed: 1.5.1]
│   ├── packaging [required: >=24.0, installed: 26.2]
│   └── pyproject_hooks [required: Any, installed: 1.2.0]
├── installer [required: >=1.0, installed: 1.0.1]
├── nab-index [required: ==0.0.14, installed: 0.0.14]
│   ├── nab-provider [required: ==0.0.14, installed: 0.0.14]
│   │   ├── nab-resolver [required: ==0.0.14, installed: 0.0.14]
│   │   └── typing_extensions [required: >=4.6, installed: 4.16.0]
│   ├── packaging [required: >=24.0, installed: 26.2]
│   ├── truststore [required: >=0.10, installed: 0.10.4]
│   ├── typing_extensions [required: >=4.6, installed: 4.16.0]
│   └── urllib3 [required: >=2.0, installed: 2.7.0]
├── nab-provider [required: ==0.0.14, installed: 0.0.14] (*)
├── nab-resolver [required: ==0.0.14, installed: 0.0.14]
├── pyproject_hooks [required: >=1.2, installed: 1.2.0]
├── tomli [required: >=2.0, installed: 2.4.1]
├── tomli_w [required: >=1.2, installed: 1.2.0]
└── typing_extensions [required: >=4.6, installed: 4.16.0]
oauthlib==3.0.0
pyjwt==1.7.1
PySocks==1.7.1
pytest-cov==7.1.0
├── coverage [required: >=7.10.6, installed: 7.15.1]
├── pluggy [required: >=1.2, installed: 1.6.0]
└── pytest [required: >=7, installed: 9.1.1]
    ├── iniconfig [required: >=1.0.1, installed: 2.3.0]
    ├── packaging [required: >=22, installed: 26.2]
    ├── pluggy [required: >=1.5,<2, installed: 1.6.0]
    └── Pygments [required: >=2.7.2, installed: 2.20.0]
requests==2.32.3
├── certifi [required: >=2017.4.17, installed: 2024.8.30]
├── charset_normalizer [required: >=2,<4, installed: 3.4.0]
├── idna [required: >=2.5,<4, installed: 3.10]
└── urllib3 [required: >=1.21.1,<3, installed: 2.7.0]

Use --exclude-dependencies to hide their transitive dependencies:

$ pipdeptree --exclude pipdeptree --exclude-dependencies
covdefaults==2.3.0
└── coverage [required: >=6.0.2, installed: 7.15.1]
cryptography==2.7
diff_cover==10.3.0
├── chardet [required: >=3.0.0, installed: 7.4.3]
├── Jinja2 [required: >=2.7.1, installed: 3.1.6]
│   └── MarkupSafe [required: >=2.0, installed: 3.0.3]
├── pluggy [required: >=0.13.1,<2, installed: 1.6.0]
└── Pygments [required: >=2.19.1,<3.0.0, installed: 2.20.0]
oauthlib==3.0.0
pyjwt==1.7.1
PySocks==1.7.1
pytest-cov==7.1.0
├── coverage [required: >=7.10.6, installed: 7.15.1]
├── pluggy [required: >=1.2, installed: 1.6.0]
└── pytest [required: >=7, installed: 9.1.1]
    ├── iniconfig [required: >=1.0.1, installed: 2.3.0]
    ├── packaging [required: >=22, installed: 26.2]
    ├── pluggy [required: >=1.5,<2, installed: 1.6.0]
    └── Pygments [required: >=2.7.2, installed: 2.20.0]
requests==2.32.3
├── certifi [required: >=2017.4.17, installed: 2024.8.30]
├── charset_normalizer [required: >=2,<4, installed: 3.4.0]
├── idna [required: >=2.5,<4, installed: 3.10]
└── urllib3 [required: >=1.21.1,<3, installed: 2.7.0]

packaging no longer appears under pytest because the command excluded it as a transitive dependency of pipdeptree.

Reverse dependency lookup

Use --reverse (-r) with --packages to find the packages that require a dependency:

$ pipdeptree --reverse --packages pygments
Pygments==2.20.0
├── diff_cover==10.3.0 [requires: Pygments>=2.19.1,<3.0.0]
└── pytest==9.1.1 [requires: Pygments>=2.7.2]
    └── pytest-cov==7.1.0 [requires: pytest>=7]

Writing requirements files

Extract top-level packages with a zero-depth tree:

$ pipdeptree --depth 0
covdefaults==2.3.0
cryptography==2.7
diff_cover==10.3.0
oauthlib==3.0.0
pipdeptree==4.0.0
pyjwt==1.7.1
PySocks==1.7.1
pytest-cov==7.1.0
requests==2.32.3

Use freeze format for pip-compatible output:

$ pipdeptree -o freeze --warn silence | grep -E '^[a-zA-Z0-9\-]+' > requirements.txt

Freeze output is a human-readable lock file with indented dependencies:

$ pipdeptree --packages pytest -o freeze
pytest==9.1.1
  iniconfig==2.3.0
  packaging==26.2
  pluggy==1.6.0
  Pygments==2.20.0

Warning control

pipdeptree warns about conflicting and circular dependencies on stderr. Control this with -w:

  • -w suppress (default): show warnings and exit 0.

  • -w silence: hide warnings and exit 0.

  • -w fail: show warnings and exit 1 if pipdeptree finds a problem (useful in CI).

A Requires-Dist entry that does not parse produces an Invalid requirement found warning, and pipdeptree leaves it out of the tree. pipdeptree treats a marker longer than 1024 bytes or with more than 16 extra comparisons the same way without parsing it, because the time and memory to parse a marker can grow exponentially with its comparisons.

$ pipdeptree -w fail
$ echo $?
0

A conflict adds warnings and a non-zero exit code:

$ pipdeptree -w fail
Jinja2==2.11.2
└── MarkupSafe [required: >=0.23, installed: 0.22]
Warning: dependency problems found:
* Jinja2==2.11.2
  - markupsafe [required: >=0.23, installed: 0.22]
------------------------------------------------------------------------
$ echo $?
1

Use from Python or a notebook

Call pipdeptree.render() when a Jupyter cell or another environment has no command-line access. It returns the dependency tree as a string without argv or stdout:

import pipdeptree

print(pipdeptree.render())                       # text tree of the current env
data = pipdeptree.render(output_format="json")   # JSON string, e.g. for json.loads
sub = pipdeptree.render(packages="rich", reverse=True)

output_format accepts text (default), json, json-tree, cyclonedx-json, mermaid and dot (Graphviz source). The programmatic renderer raises ValueError for the Graphviz formats that the dot executable renders, such as png or svg. Use dot to get the source, or use the command-line interface to render it.

The return value is a str, so print, slicing and comparisons behave as usual. The default text format implements notebook display hooks: the result renders as a Mermaid dependency diagram without a Graphviz binary, falling back to an HTML <pre> and then plain text on front-ends that do not render Mermaid. str(render()) and print(render()) give the plain text tree. The other formats (json, json-tree, cyclonedx-json, mermaid, dot) return a plain string with no rich display, so their JSON or source shows verbatim.

Unlike the CLI, pipdeptree.render() defaults to warn="silence" so a notebook cell stays free of stderr noise; pass warn="suppress" to show warnings or warn="fail" to fail on them.

Depth limiting

Limit how deep the tree renders with -d. The limit applies to text, rich, freeze and the Graphviz formats; json, json-tree, mermaid and cyclonedx-json always contain the whole graph.

$ pipdeptree -d 1 --packages pytest-cov,pipdeptree
pipdeptree==4.0.0
├── nab-index [required: >=0.0.11, installed: 0.0.14]
└── nab-project [required: >=0.0.14, installed: 0.0.14]
pytest-cov==7.1.0
├── coverage [required: >=7.10.6, installed: 7.15.1]
├── pluggy [required: >=1.2, installed: 1.6.0]
└── pytest [required: >=7, installed: 9.1.1]

Use -d 0 to show top-level packages without dependencies:

$ pipdeptree -d 0 --packages pytest-cov,pipdeptree
pipdeptree==4.0.0
pytest-cov==7.1.0

Package metadata

Display metadata fields from the package’s METADATA file with --metadata (-m). Pass a comma-separated list of field names. The renderer appends metadata to each package in parentheses:

$ pipdeptree --metadata license --packages pipdeptree --depth 0
pipdeptree==4.0.0 (MIT License)

Combine multiple fields:

$ pipdeptree --metadata license,summary --packages pipdeptree --depth 0
pipdeptree==4.0.0 (MIT License, Display installed Python package dependencies as a tree)

Common metadata fields: license, summary, author, author-email, home-page, requires-python. pipdeptree accepts fields present in the package’s METADATA file.

Note

The --license flag still works for backwards compatibility. Use --metadata license instead; version 4 deprecates --license.

Computed fields

Display computed package information with --computed (-c):

  • size – installed size on disk (human-readable)

  • size-raw – installed size in bytes (integer, useful for JSON output)

  • unique-deps-count – number of dependencies exclusive to this package (hidden when there are none)

  • unique-deps-names – names of dependencies exclusive to this package (hidden when there are none)

  • unique-deps-size – total installed size of exclusive dependencies (hidden when there are none)

The size sums the regular files a distribution’s RECORD lists. A row counts only when it resolves, after following symbolic links, inside the installation prefix that holds the site directory: <prefix> for <prefix>/lib/pythonX.Y/site-packages and <prefix>/Lib/site-packages, PythonXY for a Windows user site PythonXY/site-packages, and the scanned directory itself for any other layout, such as pip install --target. A RECORD that is not a regular file or is larger than 16 MiB counts as zero.

Console scripts under bin or Scripts and data files under share therefore count, while absolute paths and links that leave the prefix add nothing. A dist-info directory linked in from elsewhere, as in a Nix profile, also counts files under the prefix of its real location.

Unique dependencies are transitive: if removing a package would orphan a dependency, and that orphaned dependency would in turn orphan its own dependencies, the renderer counts all of them. Rich output marks unique dependencies with a ⭐ icon (alongside ✗ or ⚠ if applicable).

$ pipdeptree --computed size --packages pipdeptree --depth 0
pipdeptree==4.0.0 (0 B)
$ pipdeptree --computed unique-deps-count,unique-deps-names,unique-deps-size --packages pipdeptree --depth 0
pipdeptree==4.0.0 (11 unique deps, unique: build | installer | nab-index | nab-project | nab-provider | nab-resolver | pyproject-hooks | tomli | tomli-w | truststore | typing-extensions, unique size: 0 B)

Both --metadata and --computed work with each output format. You can combine them. In JSON output, size_raw and unique_deps_count are native integers, while unique_deps_names is a list of strings.

Including extras

The default, --extras explicit, follows an optional dependency when a parent requests that extra with name[extra]. Use --extras active to show optional groups whose complete dependency set is present:

$ pipdeptree --extras active --packages oauthlib
oauthlib==3.0.0
├── cryptography [required: Any, installed: 2.7, extra: signedtoken]
└── pyjwt [required: >=1.0.0, installed: 1.7.1, extra: signedtoken]

Optional edges carry the extra’s name. --extras none removes optional edges, while bare --extras is a compatibility spelling of --extras explicit. See How pipdeptree works for the three modes.

To surface one package’s extra, request it through --packages using the somepackage[extra] syntax from the “Filtering packages” section. pipdeptree shows that extra even with --extras none.