src/tools/cargo/src/doc/man/cargo-add.md

   1 # cargo-add(1)
   2
   3 {{*set actionverb="Add"}}
   4 {{*set nouns="adds"}}
   5
   6 ## NAME
   7
   8 cargo-add --- Add dependencies to a Cargo.toml manifest file
   9
  10 ## SYNOPSIS
  11
  12 `cargo add` [_options_] _crate_...\
  13 `cargo add` [_options_] `--path` _path_\
  14 `cargo add` [_options_] `--git` _url_ [_crate_...]\
  15
  16
  17 ## DESCRIPTION
  18
  19 This command can add or modify dependencies.
  20
  21 The source for the dependency can be specified with:
  22
  23 * _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_"
  24 * `--path` _path_: Fetch from the specified _path_
  25 * `--git` _url_: Pull from a git repo at _url_
  26
  27 If no source is specified, then a best effort will be made to select one, including:
  28
  29 * Existing dependencies in other tables (like `dev-dependencies`)
  30 * Workspace members
  31 * Latest release in the registry
  32
  33 When you add a package that is already present, the existing entry will be updated with the flags specified.
  34
  35 Upon successful invocation, the enabled (`+`) and disabled (`-`) [features] of the specified
  36 dependency will be listed in the command's output.
  37
  38 [features]: ../reference/features.md
  39
  40 ## OPTIONS
  41
  42 ### Source options
  43
  44 {{#options}}
  45
  46 {{#option "`--git` _url_" }}
  47 [Git URL to add the specified crate from](../reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories).
  48 {{/option}}
  49
  50 {{#option "`--branch` _branch_" }}
  51 Branch to use when adding from git.
  52 {{/option}}
  53
  54 {{#option "`--tag` _tag_" }}
  55 Tag to use when adding from git.
  56 {{/option}}
  57
  58 {{#option "`--rev` _sha_" }}
  59 Specific commit to use when adding from git.
  60 {{/option}}
  61
  62 {{#option "`--path` _path_" }}
  63 [Filesystem path](../reference/specifying-dependencies.html#specifying-path-dependencies) to local crate to add.
  64 {{/option}}
  65
  66 {{> options-registry }}
  67
  68 {{/options}}
  69
  70 ### Section options
  71
  72 {{#options}}
  73
  74 {{#option "`--dev`" }}
  75 Add as a [development dependency](../reference/specifying-dependencies.html#development-dependencies).
  76 {{/option}}
  77
  78 {{#option "`--build`" }}
  79 Add as a [build dependency](../reference/specifying-dependencies.html#build-dependencies).
  80 {{/option}}
  81
  82 {{#option "`--target` _target_" }}
  83 Add as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies).
  84
  85 To avoid unexpected shell expansions, you may use quotes around each target, e.g., `--target 'cfg(unix)'`.
  86 {{/option}}
  87
  88 {{/options}}
  89
  90 ### Dependency options
  91
  92 {{#options}}
  93
  94 {{#option "`--dry-run`" }}
  95 Don't actually write the manifest
  96 {{/option}}
  97
  98 {{#option "`--rename` _name_" }}
  99 [Rename](../reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml) the dependency.
 100 {{/option}}
 101
 102 {{#option "`--optional`" }}
 103 Mark the dependency as [optional](../reference/features.html#optional-dependencies).
 104 {{/option}}
 105
 106 {{#option "`--no-optional`" }}
 107 Mark the dependency as [required](../reference/features.html#optional-dependencies).
 108 {{/option}}
 109
 110 {{#option "`--no-default-features`" }}
 111 Disable the [default features](../reference/features.html#dependency-features).
 112 {{/option}}
 113
 114 {{#option "`--default-features`" }}
 115 Re-enable the [default features](../reference/features.html#dependency-features).
 116 {{/option}}
 117
 118 {{#option "`-F` _features_" "`--features` _features_" }}
 119 Space or comma separated list of [features to
 120 activate](../reference/features.html#dependency-features). When adding multiple
 121 crates, the features for a specific crate may be enabled with
 122 `package-name/feature-name` syntax. This flag may be specified multiple times,
 123 which enables all specified features.
 124 {{/option}}
 125
 126 {{#option "`--ignore-rust-version`" }}
 127 Ignore `rust-version` specification in packages.
 128
 129 This option is unstable and available only on the
 130 [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html)
 131 and requires the `-Z unstable-options` flag to enable.
 132 See <https://github.com/rust-lang/cargo/issues/5579> for more information.
 133 {{/option}}
 134
 135 {{/options}}
 136
 137
 138 ### Display Options
 139
 140 {{#options}}
 141 {{> options-display }}
 142 {{/options}}
 143
 144 ### Manifest Options
 145
 146 {{#options}}
 147 {{> options-manifest-path }}
 148
 149 {{#option "`-p` _spec_" "`--package` _spec_" }}
 150 Add dependencies to only the specified package.
 151 {{/option}}
 152
 153 {{> options-locked }}
 154 {{/options}}
 155
 156 {{> section-options-common }}
 157
 158 {{> section-environment }}
 159
 160 {{> section-exit-status }}
 161
 162 ## EXAMPLES
 163
 164 1. Add `regex` as a dependency
 165
 166        cargo add regex
 167
 168 2. Add `trybuild` as a dev-dependency
 169
 170        cargo add --dev trybuild
 171
 172 3. Add an older version of `nom` as a dependency
 173
 174        cargo add nom@5
 175
 176 4. Add support for serializing data structures to json with `derive`s
 177
 178        cargo add serde serde_json -F serde/derive
 179
 180 5. Add `windows` as a platform specific dependency on `cfg(windows)`
 181
 182        cargo add windows --target 'cfg(windows)'
 183
 184 ## SEE ALSO
 185 {{man "cargo" 1}}, {{man "cargo-remove" 1}}