| '\" t |
| .TH "CARGO\-TREE" "1" |
| .nh |
| .ad l |
| .ss \n[.ss] 0 |
| .SH "NAME" |
| cargo\-tree \[em] Display a tree visualization of a dependency graph |
| .SH "SYNOPSIS" |
| \fBcargo tree\fR [\fIoptions\fR] |
| .SH "DESCRIPTION" |
| This command will display a tree of dependencies to the terminal. An example |
| of a simple project that depends on the \[lq]rand\[rq] package: |
| .sp |
| .RS 4 |
| .nf |
| 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 |
| .fi |
| .RE |
| .sp |
| Packages marked with \fB(*)\fR have been \[lq]de\-duplicated\[rq]\&. The dependencies for the |
| package have already been shown elsewhere in the graph, and so are not |
| repeated. Use the \fB\-\-no\-dedupe\fR option to repeat the duplicates. |
| .sp |
| The \fB\-e\fR flag can be used to select the dependency kinds to display. The |
| \[lq]features\[rq] kind changes the output to display the features enabled by |
| each dependency. For example, \fBcargo tree \-e features\fR: |
| .sp |
| .RS 4 |
| .nf |
| 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 |
| .fi |
| .RE |
| .sp |
| In this tree, \fBmyproject\fR depends on \fBlog\fR with the \fBserde\fR feature. \fBlog\fR in |
| turn depends on \fBcfg\-if\fR with \[lq]default\[rq] features. When using \fB\-e features\fR it |
| can be helpful to use \fB\-i\fR flag to show how the features flow into a package. |
| See the examples below for more detail. |
| .SS "Feature Unification" |
| This command shows a graph much closer to a feature\-unified graph Cargo will |
| build, rather than what you list in \fBCargo.toml\fR\&. For instance, if you specify |
| the same dependency in both \fB[dependencies]\fR and \fB[dev\-dependencies]\fR but with |
| different features on. This command may merge all features and show a \fB(*)\fR on |
| one of the dependency to indicate the duplicate. |
| .sp |
| As a result, for a mostly equivalent overview of what \fBcargo build\fR does, |
| \fBcargo tree \-e normal,build\fR is pretty close; for a mostly equivalent overview |
| of what \fBcargo test\fR does, \fBcargo tree\fR is pretty close. However, it doesn\[cq]t |
| guarantee the exact equivalence to what Cargo is going to build, since a |
| compilation is complex and depends on lots of different factors. |
| .sp |
| To learn more about feature unification, check out this |
| \fIdedicated section\fR <https://doc.rust\-lang.org/cargo/reference/features.html#feature\-unification>\&. |
| .SH "OPTIONS" |
| .SS "Tree Options" |
| .sp |
| \fB\-i\fR \fIspec\fR, |
| \fB\-\-invert\fR \fIspec\fR |
| .RS 4 |
| Show the reverse dependencies for the given package. This flag will invert |
| the tree and display the packages that depend on the given package. |
| .sp |
| Note that in a workspace, by default it will only display the package\[cq]s |
| reverse dependencies inside the tree of the workspace member in the current |
| directory. The \fB\-\-workspace\fR flag can be used to extend it so that it will |
| show the package\[cq]s reverse dependencies across the entire workspace. The \fB\-p\fR |
| flag can be used to display the package\[cq]s reverse dependencies only with the |
| subtree of the package given to \fB\-p\fR\&. |
| .RE |
| .sp |
| \fB\-\-prune\fR \fIspec\fR |
| .RS 4 |
| Prune the given package from the display of the dependency tree. |
| .RE |
| .sp |
| \fB\-\-depth\fR \fIdepth\fR |
| .RS 4 |
| Maximum display depth of the dependency tree. A depth of 1 displays the direct |
| dependencies, for example. |
| .RE |
| .sp |
| \fB\-\-no\-dedupe\fR |
| .RS 4 |
| 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 \fB(*)\fR to indicate it has already been shown. |
| This flag will cause those duplicates to be repeated. |
| .RE |
| .sp |
| \fB\-d\fR, |
| \fB\-\-duplicates\fR |
| .RS 4 |
| Show only dependencies which come in multiple versions (implies \fB\-\-invert\fR). |
| When used with the \fB\-p\fR flag, only shows duplicates within the subtree of the |
| given package. |
| .sp |
| 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. |
| .RE |
| .sp |
| \fB\-e\fR \fIkinds\fR, |
| \fB\-\-edges\fR \fIkinds\fR |
| .RS 4 |
| The dependency kinds to display. Takes a comma separated list of values: |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBall\fR \[em] Show all edge kinds. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBnormal\fR \[em] Show normal dependencies. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBbuild\fR \[em] Show build dependencies. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBdev\fR \[em] Show development dependencies. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBfeatures\fR \[em] Show features enabled by each dependency. If this is the only |
| kind given, then it will automatically include the other dependency kinds. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBno\-normal\fR \[em] Do not include normal dependencies. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBno\-build\fR \[em] Do not include build dependencies. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBno\-dev\fR \[em] Do not include development dependencies. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBno\-proc\-macro\fR \[em] Do not include procedural macro dependencies. |
| .RE |
| .sp |
| The \fBnormal\fR, \fBbuild\fR, \fBdev\fR, and \fBall\fR dependency kinds cannot be mixed with |
| \fBno\-normal\fR, \fBno\-build\fR, or \fBno\-dev\fR dependency kinds. |
| .sp |
| The default is \fBnormal,build,dev\fR\&. |
| .RE |
| .sp |
| \fB\-\-target\fR \fItriple\fR |
| .RS 4 |
| Filter dependencies matching the given \fItarget triple\fR <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&. |
| The default is the host platform. Use the value \fBall\fR to include \fIall\fR targets. |
| .RE |
| .SS "Tree Formatting Options" |
| .sp |
| \fB\-\-charset\fR \fIcharset\fR |
| .RS 4 |
| Chooses the character set to use for the tree. Valid values are \[lq]utf8\[rq] or |
| \[lq]ascii\[rq]\&. When unspecified, cargo will auto\-select a value. |
| .RE |
| .sp |
| \fB\-f\fR \fIformat\fR, |
| \fB\-\-format\fR \fIformat\fR |
| .RS 4 |
| Set the format string for each package. The default is \[lq]{p}\[rq]\&. |
| .sp |
| This is an arbitrary string which will be used to display each package. The following |
| strings will be replaced with the corresponding value: |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fB{p}\fR \[em] The package name. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fB{l}\fR \[em] The package license. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fB{r}\fR \[em] The package repository URL. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fB{f}\fR \[em] Comma\-separated list of package features that are enabled. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fB{lib}\fR \[em] The name, as used in a \fBuse\fR statement, of the package\[cq]s library. |
| .RE |
| .RE |
| .sp |
| \fB\-\-prefix\fR \fIprefix\fR |
| .RS 4 |
| Sets how each line is displayed. The \fIprefix\fR value can be one of: |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBindent\fR (default) \[em] Shows each line indented as a tree. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBdepth\fR \[em] Show as a list, with the numeric depth printed before each entry. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBnone\fR \[em] Show as a flat list. |
| .RE |
| .RE |
| .SS "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 |
| \fB\-\-manifest\-path\fR 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. |
| .sp |
| The default members of a workspace can be set explicitly with the |
| \fBworkspace.default\-members\fR key in the root manifest. If this is not set, a |
| virtual workspace will include all workspace members (equivalent to passing |
| \fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. |
| .sp |
| \fB\-p\fR \fIspec\fR\[u2026], |
| \fB\-\-package\fR \fIspec\fR\[u2026] |
| .RS 4 |
| Display only the specified packages. See \fBcargo\-pkgid\fR(1) for the |
| SPEC format. This flag may be specified multiple times and supports common Unix |
| glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally |
| expanding glob patterns before Cargo handles them, you must use single quotes or |
| double quotes around each pattern. |
| .RE |
| .sp |
| \fB\-\-workspace\fR |
| .RS 4 |
| Display all members in the workspace. |
| .RE |
| .sp |
| \fB\-\-exclude\fR \fISPEC\fR\[u2026] |
| .RS 4 |
| Exclude the specified packages. Must be used in conjunction with the |
| \fB\-\-workspace\fR flag. This flag may be specified multiple times and supports |
| common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell |
| accidentally expanding glob patterns before Cargo handles them, you must use |
| single quotes or double quotes around each pattern. |
| .RE |
| .SS "Manifest Options" |
| .sp |
| \fB\-\-manifest\-path\fR \fIpath\fR |
| .RS 4 |
| Path to the \fBCargo.toml\fR file. By default, Cargo searches for the |
| \fBCargo.toml\fR file in the current directory or any parent directory. |
| .RE |
| .sp |
| \fB\-\-frozen\fR, |
| \fB\-\-locked\fR |
| .RS 4 |
| Either of these flags requires that the \fBCargo.lock\fR file is |
| up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will |
| exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from |
| attempting to access the network to determine if it is out\-of\-date. |
| .sp |
| These may be used in environments where you want to assert that the |
| \fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network |
| access. |
| .RE |
| .sp |
| \fB\-\-offline\fR |
| .RS 4 |
| 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. |
| .sp |
| 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 \fBcargo\-fetch\fR(1) command to download dependencies before going |
| offline. |
| .sp |
| May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| .RE |
| .SS "Feature Selection" |
| The feature flags allow you to control which features are enabled. When no |
| feature options are given, the \fBdefault\fR feature is activated for every |
| selected package. |
| .sp |
| See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> |
| for more details. |
| .sp |
| \fB\-F\fR \fIfeatures\fR, |
| \fB\-\-features\fR \fIfeatures\fR |
| .RS 4 |
| Space or comma separated list of features to activate. Features of workspace |
| members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may |
| be specified multiple times, which enables all specified features. |
| .RE |
| .sp |
| \fB\-\-all\-features\fR |
| .RS 4 |
| Activate all available features of all selected packages. |
| .RE |
| .sp |
| \fB\-\-no\-default\-features\fR |
| .RS 4 |
| Do not activate the \fBdefault\fR feature of the selected packages. |
| .RE |
| .SS "Display Options" |
| .sp |
| \fB\-v\fR, |
| \fB\-\-verbose\fR |
| .RS 4 |
| Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which |
| includes extra output such as dependency warnings and build script output. |
| May also be specified with the \fBterm.verbose\fR |
| \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| .RE |
| .sp |
| \fB\-q\fR, |
| \fB\-\-quiet\fR |
| .RS 4 |
| Do not print cargo log messages. |
| May also be specified with the \fBterm.quiet\fR |
| \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| .RE |
| .sp |
| \fB\-\-color\fR \fIwhen\fR |
| .RS 4 |
| Control when colored output is used. Valid values: |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the |
| terminal. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. |
| .RE |
| .sp |
| May also be specified with the \fBterm.color\fR |
| \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| .RE |
| .SS "Common Options" |
| .sp |
| \fB+\fR\fItoolchain\fR |
| .RS 4 |
| If Cargo has been installed with rustup, and the first argument to \fBcargo\fR |
| begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such |
| as \fB+stable\fR or \fB+nightly\fR). |
| See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> |
| for more information about how toolchain overrides work. |
| .RE |
| .sp |
| \fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR |
| .RS 4 |
| Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, |
| or provided as a path to an extra configuration file. This flag may be specified multiple times. |
| See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. |
| .RE |
| .sp |
| \fB\-C\fR \fIPATH\fR |
| .RS 4 |
| Changes the current working directory before executing any specified operations. This affects |
| things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as |
| the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must |
| appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&. |
| .sp |
| This option is only available on the \fInightly |
| channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and |
| requires the \fB\-Z unstable\-options\fR flag to enable (see |
| \fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). |
| .RE |
| .sp |
| \fB\-h\fR, |
| \fB\-\-help\fR |
| .RS 4 |
| Prints help information. |
| .RE |
| .sp |
| \fB\-Z\fR \fIflag\fR |
| .RS 4 |
| Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. |
| .RE |
| .SH "ENVIRONMENT" |
| See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for |
| details on environment variables that Cargo reads. |
| .SH "EXIT STATUS" |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. |
| .RE |
| .sp |
| .RS 4 |
| \h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. |
| .RE |
| .SH "EXAMPLES" |
| .sp |
| .RS 4 |
| \h'-04' 1.\h'+01'Display the tree for the package in the current directory: |
| .sp |
| .RS 4 |
| .nf |
| cargo tree |
| .fi |
| .RE |
| .RE |
| .sp |
| .RS 4 |
| \h'-04' 2.\h'+01'Display all the packages that depend on the \fBsyn\fR package: |
| .sp |
| .RS 4 |
| .nf |
| cargo tree \-i syn |
| .fi |
| .RE |
| .RE |
| .sp |
| .RS 4 |
| \h'-04' 3.\h'+01'Show the features enabled on each package: |
| .sp |
| .RS 4 |
| .nf |
| cargo tree \-\-format "{p} {f}" |
| .fi |
| .RE |
| .RE |
| .sp |
| .RS 4 |
| \h'-04' 4.\h'+01'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). |
| .sp |
| .RS 4 |
| .nf |
| cargo tree \-d |
| .fi |
| .RE |
| .RE |
| .sp |
| .RS 4 |
| \h'-04' 5.\h'+01'Explain why features are enabled for the \fBsyn\fR package: |
| .sp |
| .RS 4 |
| .nf |
| cargo tree \-e features \-i syn |
| .fi |
| .RE |
| .sp |
| The \fB\-e features\fR flag is used to show features. The \fB\-i\fR flag is used to |
| invert the graph so that it displays the packages that depend on \fBsyn\fR\&. An |
| example of what this would display: |
| .sp |
| .RS 4 |
| .nf |
| 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" (*) |
| .fi |
| .RE |
| .sp |
| To read this graph, you can follow the chain for each feature from the root |
| to see why it is included. For example, the \[lq]full\[rq] feature is added by the |
| \fBrustversion\fR crate which is included from \fBmyproject\fR (with the default |
| features), and \fBmyproject\fR is the package selected on the command\-line. All |
| of the other \fBsyn\fR features are added by the \[lq]default\[rq] feature (\[lq]quote\[rq] is |
| added by \[lq]printing\[rq] and \[lq]proc\-macro\[rq], both of which are default features). |
| .sp |
| If you\[cq]re having difficulty cross\-referencing the de\-duplicated \fB(*)\fR |
| entries, try with the \fB\-\-no\-dedupe\fR flag to get the full output. |
| .RE |
| .SH "SEE ALSO" |
| \fBcargo\fR(1), \fBcargo\-metadata\fR(1) |