uv tree

Display the project’s dependency tree

Display the dependency tree for the project.

Usage

uv tree [OPTIONS]

Description

Display the project’s dependency tree, showing how packages depend on each other.

By default, the tree is filtered to match the current platform and Python version. Use --universal to display the tree for all platforms, or use --python-version or --python-platform to filter for specific environments.

Options

Display Options

--universal

Show a platform-independent dependency tree.

Shows resolved package versions for all Python versions and platforms, rather than filtering to those that are relevant for the current environment.

Multiple versions may be shown for each package.

--depth · number

Maximum display depth of the dependency tree.

Short form: -d

--prune · string[]

Prune the given package from the display of the dependency tree.

--package · string[]

Display only the specified packages.

--no-dedupe

Do not de-duplicate repeated dependencies.

By default, uv will de-duplicate dependencies that appear multiple times in the tree.

--invert

Show the reverse dependencies for the given package.

Short form: -i

Dependency Selection

--group · string[]

Include dependencies from the specified dependency group.

May be provided multiple times.

--no-group · string[]

Disable the specified dependency group.

This option always takes precedence over default groups, --all-groups, and --group.

May be provided multiple times.

Environment variable: UV_NO_GROUP

--all-groups

Include dependencies from all dependency groups.

--no-group can be used to exclude specific groups.

--no-default-groups

Ignore the default dependency groups.

uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.

Environment variable: UV_NO_DEFAULT_GROUPS

--only-group · string[]

Only include dependencies from the specified dependency group.

The project and its dependencies will be omitted.

May be provided multiple times. Implies --no-default-groups.

--only-dev

Only include the development dependency group.

The project and its dependencies will be omitted.

This option is an alias for --only-group dev. Implies --no-default-groups.

Locking Options

--locked

Assert that the uv.lock will remain unchanged.

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

Environment variable: UV_LOCKED

--frozen

Display the requirements without locking the project.

If the lockfile is missing, uv will exit with an error.

Environment variable: UV_FROZEN

Script Options

--script · path

Show the dependency tree for the specified PEP 723 Python script, rather than the current project.

If provided, uv will resolve the dependencies based on its inline metadata table, in adherence with PEP 723.

Python Options

--python · string

The Python interpreter to use for locking and filtering.

By default, the tree is filtered to match the platform as reported by the Python interpreter. Use --universal to display the tree for all platforms, or use --python-version or --python-platform to override a subset of markers.

See uv help python for details on Python discovery and supported request formats.

Short form: -p
Environment variable: UV_PYTHON

--python-version · string

The Python version to use when filtering the tree.

For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10.

Defaults to the version of the discovered Python interpreter.

--python-platform · string

The platform to use when filtering the tree.

For example, pass --platform windows to display the dependencies that would be included when installing on Windows.

Represented as a “target triple”, a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

Examples

Display basic dependency tree

uv tree

Shows the dependency tree for the current project.

Show universal tree

uv tree --universal

Displays dependencies for all platforms and Python versions.

Limit tree depth

uv tree --depth 2

Shows only the first two levels of dependencies.

Show reverse dependencies

uv tree --invert requests

Shows which packages depend on requests.

Prune packages from display

uv tree --prune pytest --prune mypy

Hides pytest and mypy from the tree (but shows their dependencies).

Show specific packages

uv tree --package requests --package urllib3

Displays only the subtrees for requests and urllib3.

Show without deduplication

uv tree --no-dedupe

Shows all instances of dependencies, even if they appear multiple times.

Filter by Python version

uv tree --python-version 3.10

Shows dependencies as they would be resolved for Python 3.10.

Filter by platform

uv tree --python-platform linux

Shows dependencies for Linux.

Show tree for a script

uv tree --script my_script.py

Displays the dependency tree for a PEP 723 script.

Show only dev dependencies

uv tree --only-dev

Include specific dependency groups

uv tree --group test --group docs

Common Patterns

Debugging dependency conflicts

# See full tree without deduplication
uv tree --no-dedupe

# Find what depends on a specific package
uv tree --invert problematic-package

Checking cross-platform dependencies

# Check Linux dependencies
uv tree --python-platform x86_64-unknown-linux-gnu

# Check macOS dependencies  
uv tree --python-platform aarch64-apple-darwin

# Check Windows dependencies
uv tree --python-platform x86_64-pc-windows-msvc

Understanding dependency depth

# See immediate dependencies only
uv tree --depth 1

# See two levels
uv tree --depth 2

Analyzing specific packages

# Show only web-related dependencies
uv tree --package fastapi --package uvicorn --package pydantic

# Hide test dependencies from view
uv tree --prune pytest --prune hypothesis

CI/CD verification

# Ensure tree matches expectations
uv tree --frozen

Output Format

The tree output shows package dependencies in a hierarchical format:

my-project v0.1.0
├── requests v2.31.0
│   ├── charset-normalizer v3.3.2
│   ├── idna v3.6
│   ├── urllib3 v2.1.0
│   └── certifi v2023.11.17
└── rich v13.7.0
    ├── markdown-it-py v3.0.0
    │   └── mdurl v0.1.2
    └── pygments v2.17.2

When using --invert, the tree is reversed to show dependents:

requests v2.31.0
└── my-project v0.1.0

Related Commands

• uv lock - Update the lockfile
• uv sync - Sync the environment
• uv add - Add dependencies
• uv remove - Remove dependencies