[[viewing-debugging-dependencies]]
= Viewing and debugging dependencies

Gradle provides sufficient tooling to navigate large dependency graphs and mitigate situations that can lead to link:https://en.wikipedia.org/wiki/Dependency_hell[dependency hell].
Users can choose to render the full graph of dependencies as well as identify the selection reason and origin for a dependency.
The origin of a dependency can be a declared dependency in the build script or a transitive dependency in graph plus their corresponding configuration.
Gradle offers both capabilities through visual representation via build scans and as command line tooling.

[[sec:debugging-build-scans]]
== Build scans

[NOTE]
====
If you do not know what link:https://scans.gradle.com/[build scan]s are, be sure to check them out!
====

A build scan can visualize dependencies as a navigable, searchable tree.
Additional context information can be rendered by clicking on a specific dependency in the graph.

.Dependency tree in a build scan
image::dependency-management-dependencies-report-build-scan.png[]

[[sec:listing_dependencies]]
== Listing dependencies in a project

Gradle can visualize the whole dependency tree for every <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,configuration>> available in the project.

Rendering the dependency tree is particularly useful if you'd like to identify which dependencies have been resolved at runtime.
It also provides you with information about any dependency conflict resolution that occurred in the process and clearly indicates the selected version.
The dependency report always contains declared and transitive dependencies.

[NOTE]
====
The `dependencies` task selector will only execute the `dependencies` task on a _single_ project.
If you run the task on the root project, it will show dependencies of the root project and not of any subproject.
Be sure to always target the <<command_line_interface#executing_tasks_in_multi_project_builds, right project>> when running `dependencies`.
====

Let's say you'd want to create tasks for your project that use the link:https://www.eclipse.org/jgit/[JGit library] to execute SCM operations e.g. to model a release process.
You can declare dependencies for any external tooling with the help of a <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,custom configuration>> so that it doesn't pollute other contexts like the compilation classpath for your production source code.

Every Gradle project provides the task `dependencies` to render the so-called _dependency report_ from the command line.
By default the dependency report renders dependencies for all configurations.
To focus on the information about one configuration, provide the optional parameter `--configuration`.

For example, to show dependencies that would be on the test runtime classpath in a Java project, run:

----
gradle -q dependencies --configuration testRuntimeClasspath
----

TIP: Just like with <<command_line_interface#sec:name_abbreviation, project and task names>>, you can use abbreviated names to select a configuration. For example, you can specify `tRC` instead of `testRuntimeClasspath` if the pattern matches to a single configuration.

TIP: To see a list of all the pre-defined configurations added by the `java` plugin, see <<java_plugin.adoc#sec:java_plugin_and_dependency_management,the documentation for the Java Plugin>>.

.Declaring the JGit dependency with a custom configuration
====
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependenciesReport/groovy",files="build.gradle[tags=dependency-declaration]"]
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependenciesReport/kotlin",files="build.gradle.kts[tags=dependency-declaration]"]
====

=== Example: Rendering the dependency report for a custom configuration

.Output of **`gradle -q dependencies --configuration scm`**
----
> gradle -q dependencies --configuration scm
include::{snippetsPath}/dependencyManagement/inspectingDependencies-dependenciesReport/tests/dependencyReport.out[]
----

The dependencies report provides detailed information about the dependencies available in the graph.
Any dependency that could not be resolved is marked with `FAILED` in red color.
Dependencies with the same coordinates that can occur multiple times in the graph are omitted and indicated by an asterisk.
Dependencies that had to undergo conflict resolution render the requested and selected version separated by a right arrow character.

[[sec:identifying_reason_dependency_selection]]
== Identifying which dependency version was selected and why

Large software projects inevitably deal with an increased number of dependencies either through direct or transitive dependencies.
The <<#sec:listing_dependencies,dependencies report>> provides you with the raw list of dependencies but does not explain _why_ they have been selected or _which_ dependency is responsible for pulling them into the graph.

Let's have a look at a concrete example.
A project may request two different versions of the same dependency either as direct or transitive dependency.
Gradle applies <<dependency_resolution.adoc#sec:version-conflict,version conflict resolution>> to ensure that only one version of the dependency exists in the dependency graph.
In this example the conflicting dependency is represented by `commons-codec:commons-codec`.

.Declaring the JGit dependency and a conflicting dependency
====
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependencyInsightReport/groovy",files="build.gradle[tags=dependency-declaration]"]
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependencyInsightReport/kotlin",files="build.gradle.kts[tags=dependency-declaration]"]
====

The dependency tree in a link:https://scans.gradle.com/[build scan] renders the selection reason (conflict resolution) as well as the origin of a dependency if you click on a dependency and select the "Required By" tab.

.Dependency insight capabilities in a build scan
image::dependency-management-dependency-insight-report-build-scan.png[]

Every Gradle project provides the task `dependencyInsight` to render the so-called  _dependency insight report_ from the command line.
Given a dependency in the dependency graph you can identify the selection reason and track down the origin of the dependency selection.
You can think of the dependency insight report as the inverse representation of the dependency report for a given dependency.

The task takes the following parameters:

`--dependency <dependency>` (mandatory)::
Indicates which dependency to focus on.
It can be a complete `group:name`, or part of it.
If multiple dependencies match, they are all printed in the report.
`--configuration <name>` (mandatory)::
Indicates which configuration to resolve for showing the dependency information (_camelCase_ also supported like in `dependencies` task).
Note that the <<java_plugin#java_plugin, Java plugin>> wires a convention with the value `compileClasspath`, making the parameter optional.
`--single-path` (optional)::
Indicates to render only a single path to the dependency.
This might be useful to trim down the output in large graphs.

[NOTE]
====
The `dependencyInsight` task selector will only execute the `dependencyInsight` task on a _single_ project.
If you run the task on the root project, it will show the dependency information of the root project and not of any subproject.
Be sure to always target the <<command_line_interface#executing_tasks_in_multi_project_builds, right project>> when running `dependencyInsight`.
====

=== Example: Using the dependency insight report for a given dependency

.Output of **`gradle -q dependencyInsight --dependency commons-codec --configuration scm`**
----
> gradle -q dependencyInsight --dependency commons-codec --configuration scm
include::{snippetsPath}/dependencyManagement/inspectingDependencies-dependencyInsightReport/tests/dependencyInsightReport.out[]
----

As indicated above, omitting the `--configuration` parameter in a project that is not a Java project will lead to an error:
----
> Dependency insight report cannot be generated because the input configuration was not specified.
  It can be specified from the command line, e.g: ':dependencyInsight --configuration someConf --dependency someDep'
----

For more information about configurations, see the documentation on declaring dependencies, which describes <<declaring_dependencies.adoc#sec:what-are-dependency-configurations, what dependency configurations are>>.

=== Understanding selection reasons

The "Selection reasons" part of the dependency insight report will list the different reasons as to why a dependency was selected.
Have a look at the table below to understand the meaning of the different terms used:

.Selections reasons terminology
[%header%autowidth,compact]
|===
| Reason    | Meaning

| (Absent)
| This means that no other reason than having a reference, direct or transitive, was present

| Was requested : <text>
| The dependency appears in the graph, and the inclusion came with a <<declaring_dependencies#sec:documenting-dependencies, `because` text>>.

| Was requested : didn't match versions <versions>
| The dependency appears in the graph, with a <<dynamic_versions#sub:declaring_dependency_with_dynamic_version, dynamic version>>, which did not include the listed versions.
This can also be followed by a `because` text.

| Was requested : reject version <versions>
| The dependency appears in the graph, with a <<rich_versions#rich-version-constraints, rich version>> containing one or more `reject`.
This can also be followed by a `because` text.

| By conflict resolution : between versions <version>
| The dependency appeared multiple times in the graph, with different version requests.
This resulted in <<dependency_resolution#sec:version-conflict, conflict resolution>> to select the most appropriate version.

| By constraint
| A <<dependency_constraints#sec:adding-constraints-transitive-deps, dependency constraint>> participated in the version selection.
This can also be followed by a `because` text.

| By ancestor
| There is a <<rich_versions#rich-version-constraints, rich version>> with a `strictly` in the graph which enforces the version of this dependency.

| Selected by rule
| A <<resolution_rules#resolution_rules, dependency resolution rule>> overruled the default selection process.
This can also be followed by a `because` text.

| Rejection : <version> by rule because <text>
| A `ComponentSelection.reject` link:{groovyDslPath}/org.gradle.api.artifacts.ComponentSelection.html#org.gradle.api.artifacts.ComponentSelection:reject(java.lang.String)[rejected the given version] of the dependency

| Rejection: version <version>: <attributes information>
| The dependency has a dynamic version, and some versions did not match the <<variant_model#sec:variant-aware-matching, requested attributes>>.

| Forced
| The build <<dependency_downgrade_and_exclude#forced_dependencies_vs_strict_dependencies, enforces>> the version of the dependency.
|===

Note that if multiple selection reasons exist in the graph, they will all be listed.


[[sec:resolving-version-conflict]]
== Resolving version conflicts

If the selected version does not match your expectation, Gradle offers a series of tools to help you <<dependency_constraints.adoc#dependency-constraints,control transitive dependencies>>.

[[sec:resolving-variant-aware-errors]]
== Resolving variant selection errors

Sometimes a selection error will happen at the <<variant_model.adoc#understanding-variant-selection,variant selection level>>.
Have a look at the <<variant_model.adoc#sec:variant-select-errors,dedicated section>> to understand these errors and how to resolve them.

[[sub:resolving-unsafe-configuration-resolution-errors]]
== Resolving unsafe configuration resolution errors

Resolving a configuration can have side effects on Gradle's project model, so Gradle needs manage access to each project's configurations.
There are a number of ways a configuration might be resolved unsafely.
Gradle will produce a deprecation warning for each unsafe access.
Each of these are bad practices and can cause strange and indeterminate errors.

If your build has an unsafe access deprecation warning, it needs to be fixed.

For example:

* A task from one project directly resolves a configuration in another project in the task's action.
* A task specifies a configuration from another project as an input file collection.
* A build script for one project resolves a configuration in another project during evaluation.
* Project configurations are resolved in the settings file.

In most cases, this issue can be resolved by creating a cross-project dependency on the other project.
See the documentation for <<cross_project_publications.adoc#cross_project_publications, sharing outputs between projects>> for more information.

If you find a use case that can't be resolved using these techniques, please let us know by filing a https://github.com/gradle/gradle/issues[GitHub Issue] adhering to our issue guidelines.
