| CARGO-TREE(1) |
| |
| NAME |
| cargo-tree - Display a tree visualization of a dependency graph |
| |
| SYNOPSIS |
| cargo tree [options] |
| |
| DESCRIPTION |
| This command will display a tree of dependencies to the terminal. An |
| example of a simple project that depends on the "rand" package: |
| |
| myproject v0.1.0 (/myproject) |
| └── rand v0.7.3 |
| ├── getrandom v0.1.14 |
| │ ├── cfg-if v0.1.10 |
| │ └── libc v0.2.68 |
| ├── libc v0.2.68 (*) |
| ├── rand_chacha v0.2.2 |
| │ ├── ppv-lite86 v0.2.6 |
| │ └── rand_core v0.5.1 |
| │ └── getrandom v0.1.14 (*) |
| └── rand_core v0.5.1 (*) |
| [build-dependencies] |
| └── cc v1.0.50 |
| |
| Packages marked with (*) have been "de-duplicated". The dependencies for |
| the package have already been shown elsewhere in the graph, and so are |
| not repeated. Use the --no-dedupe option to repeat the duplicates. |
| |
| The -e flag can be used to select the dependency kinds to display. The |
| "features" kind changes the output to display the features enabled by |
| each dependency. For example, cargo tree -e features: |
| |
| myproject v0.1.0 (/myproject) |
| └── log feature "serde" |
| └── log v0.4.8 |
| ├── serde v1.0.106 |
| └── cfg-if feature "default" |
| └── cfg-if v0.1.10 |
| |
| In this tree, myproject depends on log with the serde feature. log in |
| turn depends on cfg-if with "default" features. When using -e features |
| it can be helpful to use -i flag to show how the features flow into a |
| package. See the examples below for more detail. |
| |
| Feature Unification |
| This command shows a graph much closer to a feature-unified graph Cargo |
| will build, rather than what you list in Cargo.toml. For instance, if |
| you specify the same dependency in both [dependencies] and |
| [dev-dependencies] but with different features on. This command may |
| merge all features and show a (*) on one of the dependency to indicate |
| the duplicate. |
| |
| As a result, for a mostly equivalent overview of what cargo build does, |
| cargo tree -e normal,build is pretty close; for a mostly equivalent |
| overview of what cargo test does, cargo tree is pretty close. However, |
| it doesn't guarantee the exact equivalence to what Cargo is going to |
| build, since a compilation is complex and depends on lots of different |
| factors. |
| |
| To learm more about feature unification, check out this dedicated |
| section |
| <https://doc.rust-lang.org/cargo/reference/features.html#feature-unification>. |
| |
| OPTIONS |
| Tree Options |
| -i spec, --invert spec |
| Show the reverse dependencies for the given package. This flag will |
| invert the tree and display the packages that depend on the given |
| package. |
| |
| Note that in a workspace, by default it will only display the |
| package's reverse dependencies inside the tree of the workspace |
| member in the current directory. The --workspace flag can be used to |
| extend it so that it will show the package's reverse dependencies |
| across the entire workspace. The -p flag can be used to display the |
| package's reverse dependencies only with the subtree of the package |
| given to -p. |
| |
| --prune spec |
| Prune the given package from the display of the dependency tree. |
| |
| --depth depth |
| Maximum display depth of the dependency tree. A depth of 1 displays |
| the direct dependencies, for example. |
| |
| --no-dedupe |
| Do not de-duplicate repeated dependencies. Usually, when a package |
| has already displayed its dependencies, further occurrences will not |
| re-display its dependencies, and will include a (*) to indicate it |
| has already been shown. This flag will cause those duplicates to be |
| repeated. |
| |
| -d, --duplicates |
| Show only dependencies which come in multiple versions (implies |
| --invert). When used with the -p flag, only shows duplicates within |
| the subtree of the given package. |
| |
| It can be beneficial for build times and executable sizes to avoid |
| building that same package multiple times. This flag can help |
| identify the offending packages. You can then investigate if the |
| package that depends on the duplicate with the older version can be |
| updated to the newer version so that only one instance is built. |
| |
| -e kinds, --edges kinds |
| The dependency kinds to display. Takes a comma separated list of |
| values: |
| |
| o all — Show all edge kinds. |
| |
| o normal — Show normal dependencies. |
| |
| o build — Show build dependencies. |
| |
| o dev — Show development dependencies. |
| |
| o features — Show features enabled by each dependency. If this is |
| the only kind given, then it will automatically include the other |
| dependency kinds. |
| |
| o no-normal — Do not include normal dependencies. |
| |
| o no-build — Do not include build dependencies. |
| |
| o no-dev — Do not include development dependencies. |
| |
| o no-proc-macro — Do not include procedural macro dependencies. |
| |
| The normal, build, dev, and all dependency kinds cannot be mixed |
| with no-normal, no-build, or no-dev dependency kinds. |
| |
| The default is normal,build,dev. |
| |
| --target triple |
| Filter dependencies matching the given target-triple. The default is |
| the host platform. Use the value all to include all targets. |
| |
| Tree Formatting Options |
| --charset charset |
| Chooses the character set to use for the tree. Valid values are |
| "utf8" or "ascii". Default is "utf8". |
| |
| -f format, --format format |
| Set the format string for each package. The default is "{p}". |
| |
| This is an arbitrary string which will be used to display each |
| package. The following strings will be replaced with the |
| corresponding value: |
| |
| o {p} — The package name. |
| |
| o {l} — The package license. |
| |
| o {r} — The package repository URL. |
| |
| o {f} — Comma-separated list of package features that are |
| enabled. |
| |
| o {lib} — The name, as used in a use statement, of the package's |
| library. |
| |
| --prefix prefix |
| Sets how each line is displayed. The prefix value can be one of: |
| |
| o indent (default) — Shows each line indented as a tree. |
| |
| o depth — Show as a list, with the numeric depth printed before |
| each entry. |
| |
| o none — Show as a flat list. |
| |
| Package Selection |
| By default, when no package selection options are given, the packages |
| selected depend on the selected manifest file (based on the current |
| working directory if --manifest-path is not given). If the manifest is |
| the root of a workspace then the workspaces default members are |
| selected, otherwise only the package defined by the manifest will be |
| selected. |
| |
| The default members of a workspace can be set explicitly with the |
| workspace.default-members key in the root manifest. If this is not set, |
| a virtual workspace will include all workspace members (equivalent to |
| passing --workspace), and a non-virtual workspace will include only the |
| root crate itself. |
| |
| -p spec..., --package spec... |
| Display only the specified packages. See cargo-pkgid(1) for the SPEC |
| format. This flag may be specified multiple times and supports |
| common Unix glob patterns like *, ? and []. However, to avoid your |
| shell accidentally expanding glob patterns before Cargo handles |
| them, you must use single quotes or double quotes around each |
| pattern. |
| |
| --workspace |
| Display all members in the workspace. |
| |
| --exclude SPEC... |
| Exclude the specified packages. Must be used in conjunction with the |
| --workspace flag. This flag may be specified multiple times and |
| supports common Unix glob patterns like *, ? and []. However, to |
| avoid your shell accidentally expanding glob patterns before Cargo |
| handles them, you must use single quotes or double quotes around |
| each pattern. |
| |
| Manifest Options |
| --manifest-path path |
| Path to the Cargo.toml file. By default, Cargo searches for the |
| Cargo.toml file in the current directory or any parent directory. |
| |
| --frozen, --locked |
| Either of these flags requires that the Cargo.lock file is |
| up-to-date. If the lock file is missing, or it needs to be updated, |
| Cargo will exit with an error. The --frozen flag also prevents Cargo |
| from attempting to access the network to determine if it is |
| out-of-date. |
| |
| These may be used in environments where you want to assert that the |
| Cargo.lock file is up-to-date (such as a CI build) or want to avoid |
| network access. |
| |
| --offline |
| Prevents Cargo from accessing the network for any reason. Without |
| this flag, Cargo will stop with an error if it needs to access the |
| network and the network is not available. With this flag, Cargo will |
| attempt to proceed without the network if possible. |
| |
| Beware that this may result in different dependency resolution than |
| online mode. Cargo will restrict itself to crates that are |
| downloaded locally, even if there might be a newer version as |
| indicated in the local copy of the index. See the cargo-fetch(1) |
| command to download dependencies before going offline. |
| |
| May also be specified with the net.offline config value |
| <https://doc.rust-lang.org/cargo/reference/config.html>. |
| |
| Feature Selection |
| The feature flags allow you to control which features are enabled. When |
| no feature options are given, the default feature is activated for every |
| selected package. |
| |
| See the features documentation |
| <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> |
| for more details. |
| |
| -F features, --features features |
| Space or comma separated list of features to activate. Features of |
| workspace members may be enabled with package-name/feature-name |
| syntax. This flag may be specified multiple times, which enables all |
| specified features. |
| |
| --all-features |
| Activate all available features of all selected packages. |
| |
| --no-default-features |
| Do not activate the default feature of the selected packages. |
| |
| Display Options |
| -v, --verbose |
| Use verbose output. May be specified twice for "very verbose" output |
| which includes extra output such as dependency warnings and build |
| script output. May also be specified with the term.verbose config |
| value <https://doc.rust-lang.org/cargo/reference/config.html>. |
| |
| -q, --quiet |
| Do not print cargo log messages. May also be specified with the |
| term.quiet config value |
| <https://doc.rust-lang.org/cargo/reference/config.html>. |
| |
| --color when |
| Control when colored output is used. Valid values: |
| |
| o auto (default): Automatically detect if color support is |
| available on the terminal. |
| |
| o always: Always display colors. |
| |
| o never: Never display colors. |
| |
| May also be specified with the term.color config value |
| <https://doc.rust-lang.org/cargo/reference/config.html>. |
| |
| Common Options |
| +toolchain |
| If Cargo has been installed with rustup, and the first argument to |
| cargo begins with +, it will be interpreted as a rustup toolchain |
| name (such as +stable or +nightly). See the rustup documentation |
| <https://rust-lang.github.io/rustup/overrides.html> for more |
| information about how toolchain overrides work. |
| |
| --config KEY=VALUE or PATH |
| Overrides a Cargo configuration value. The argument should be in |
| TOML syntax of KEY=VALUE, or provided as a path to an extra |
| configuration file. This flag may be specified multiple times. See |
| the command-line overrides section |
| <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> |
| for more information. |
| |
| -h, --help |
| Prints help information. |
| |
| -Z flag |
| Unstable (nightly-only) flags to Cargo. Run cargo -Z help for |
| details. |
| |
| ENVIRONMENT |
| See the reference |
| <https://doc.rust-lang.org/cargo/reference/environment-variables.html> |
| for details on environment variables that Cargo reads. |
| |
| EXIT STATUS |
| o 0: Cargo succeeded. |
| |
| o 101: Cargo failed to complete. |
| |
| EXAMPLES |
| 1. Display the tree for the package in the current directory: |
| |
| cargo tree |
| |
| 2. Display all the packages that depend on the syn package: |
| |
| cargo tree -i syn |
| |
| 3. Show the features enabled on each package: |
| |
| cargo tree --format "{p} {f}" |
| |
| 4. Show all packages that are built multiple times. This can happen if |
| multiple semver-incompatible versions appear in the tree (like 1.0.0 |
| and 2.0.0). |
| |
| cargo tree -d |
| |
| 5. Explain why features are enabled for the syn package: |
| |
| cargo tree -e features -i syn |
| |
| The -e features flag is used to show features. The -i flag is used to |
| invert the graph so that it displays the packages that depend on syn. |
| An example of what this would display: |
| |
| syn v1.0.17 |
| ├── syn feature "clone-impls" |
| │ └── syn feature "default" |
| │ └── rustversion v1.0.2 |
| │ └── rustversion feature "default" |
| │ └── myproject v0.1.0 (/myproject) |
| │ └── myproject feature "default" (command-line) |
| ├── syn feature "default" (*) |
| ├── syn feature "derive" |
| │ └── syn feature "default" (*) |
| ├── syn feature "full" |
| │ └── rustversion v1.0.2 (*) |
| ├── syn feature "parsing" |
| │ └── syn feature "default" (*) |
| ├── syn feature "printing" |
| │ └── syn feature "default" (*) |
| ├── syn feature "proc-macro" |
| │ └── syn feature "default" (*) |
| └── syn feature "quote" |
| ├── syn feature "printing" (*) |
| └── syn feature "proc-macro" (*) |
| |
| To read this graph, you can follow the chain for each feature from |
| the root to see why it is included. For example, the "full" feature |
| is added by the rustversion crate which is included from myproject |
| (with the default features), and myproject is the package selected on |
| the command-line. All of the other syn features are added by the |
| "default" feature ("quote" is added by "printing" and "proc-macro", |
| both of which are default features). |
| |
| If you're having difficulty cross-referencing the de-duplicated (*) |
| entries, try with the --no-dedupe flag to get the full output. |
| |
| SEE ALSO |
| cargo(1), cargo-metadata(1) |
| |