/commands/poetry/poetry-show-tree
poetry show --tree: show the dependency tree of a Poetry project
- tool
- Poetry
- versions
- Poetry 1.2+, Poetry 2.x
- os
- any
poetry show --tree prints your project's direct dependencies and, under each one, the packages it requires with the version constraints it declares, read from poetry.lock. poetry show without options lists every locked package with its exact version and summary, and poetry show requests shows the details of one package. Run poetry lock first if there is no lock file.
Tree and flat list
cat > pyproject.toml <<'EOF'
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["requests (==2.32.3)"]
[tool.poetry]
package-mode = false
EOF
P="uvx -q poetry@2.5.1"
$P config virtualenvs.in-project true --local
$P lock -q
$P show --tree
echo "--- top level only"
$P show --top-levelOutput
requests 2.32.3 Python HTTP for Humans. ├── certifi >=2017.4.17 ├── charset-normalizer >=2,<4 ├── idna >=2.5,<4 └── urllib3 >=1.21.1,<3 --- top level only requests (!) 2.32.3 Python HTTP for Humans.
The tree shows what requests asks for (idna >=2.5,<4), not which version was picked; poetry show without --tree lists the picked versions. The (!) marker means the package is locked but not installed yet, because this example only ran poetry lock. The example starts Poetry through uvx poetry@2.5.1; with Poetry installed the commands are poetry show --tree and poetry show --top-level.
Options
| Command | What it does |
|---|---|
| poetry show | Every locked package with version and summary |
| poetry show --tree | Direct dependencies with their requirements, as a tree |
| poetry show --tree requests | The tree below one package |
| poetry show --tree --why idna | Which packages require idna (reverse tree) |
| poetry show -T (--top-level) | Only the dependencies declared in pyproject.toml |
| poetry show -o (--outdated) | Packages with a newer version available |
| poetry show -l (--latest) | Add the latest available version to the list |
| poetry show --only main | Only the main group; --with and --without pick groups |
| poetry show requests | Details of one package: version, description, dependencies |
Reading the tree
Each top-level line is a dependency from pyproject.toml with its locked version and summary. Indented lines are requirements of that package as constraints (>=2.5,<4); deeper levels show requirements of requirements. A package that appears in several branches is installed once, at the single version in poetry.lock that satisfies every constraint. To see that version, run poetry show package.
Pitfalls
- No lock file. In Poetry 2
poetry showneedspoetry.lock; without it you get an error asking you to runpoetry lock. - Stale lock file. If
pyproject.tomlwas edited after locking, the output reflects the old lock.poetry check --locktells you, and the error is pyproject.toml changed significantly. - Groups. By default every group is shown, including
dev. Use--only mainto see what a production install contains. - Not the installed environment. The list comes from the lock file; a package installed by hand with pip in the same venv does not appear.
How to confirm it worked
poetry show package for any name in the tree prints its exact locked version. After poetry install, the (!) markers disappear from poetry show, which confirms that the environment matches the lock file.
FAQ
What does (!) mean in poetry show?
The package is in poetry.lock but not installed in the current environment. Run poetry install (or poetry sync) to install what the lock file lists.
How do I find out why a package is installed?
Run poetry show --tree --why package. With --why, the tree for a single package is printed the other way round: it shows which packages require it, up to your direct dependencies.
How do I list only outdated packages?
poetry show --outdated (-o) lists packages with a newer version available, with the current and latest version. Add --top-level to limit it to your direct dependencies.