1# cargo-run(1) 2 3 4## NAME 5 6cargo-run - Run the current package 7 8## SYNOPSIS 9 10`cargo run` [_options_] [`--` _args_] 11 12## DESCRIPTION 13 14Run a binary or example of the local package. 15 16All the arguments following the two dashes (`--`) are passed to the binary to 17run. If you're passing arguments to both Cargo and the binary, the ones after 18`--` go to the binary, the ones before go to Cargo. 19 20## OPTIONS 21 22### Package Selection 23 24By default, the package in the current working directory is selected. The `-p` 25flag can be used to choose a different package in a workspace. 26 27<dl> 28 29<dt class="option-term" id="option-cargo-run--p"><a class="option-anchor" href="#option-cargo-run--p"></a><code>-p</code> <em>spec</em></dt> 30<dt class="option-term" id="option-cargo-run---package"><a class="option-anchor" href="#option-cargo-run---package"></a><code>--package</code> <em>spec</em></dt> 31<dd class="option-desc">The package to run. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC 32format.</dd> 33 34 35</dl> 36 37 38### Target Selection 39 40When no target selection options are given, `cargo run` will run the binary 41target. If there are multiple binary targets, you must pass a target flag to 42choose one. Or, the `default-run` field may be specified in the `[package]` 43section of `Cargo.toml` to choose the name of the binary to run by default. 44 45<dl> 46 47<dt class="option-term" id="option-cargo-run---bin"><a class="option-anchor" href="#option-cargo-run---bin"></a><code>--bin</code> <em>name</em></dt> 48<dd class="option-desc">Run the specified binary.</dd> 49 50 51<dt class="option-term" id="option-cargo-run---example"><a class="option-anchor" href="#option-cargo-run---example"></a><code>--example</code> <em>name</em></dt> 52<dd class="option-desc">Run the specified example.</dd> 53 54 55</dl> 56 57### Feature Selection 58 59The feature flags allow you to control which features are enabled. When no 60feature options are given, the `default` feature is activated for every 61selected package. 62 63See [the features documentation](../reference/features.html#command-line-feature-options) 64for more details. 65 66<dl> 67 68<dt class="option-term" id="option-cargo-run---features"><a class="option-anchor" href="#option-cargo-run---features"></a><code>--features</code> <em>features</em></dt> 69<dd class="option-desc">Space or comma separated list of features to activate. Features of workspace 70members may be enabled with <code>package-name/feature-name</code> syntax. This flag may 71be specified multiple times, which enables all specified features.</dd> 72 73 74<dt class="option-term" id="option-cargo-run---all-features"><a class="option-anchor" href="#option-cargo-run---all-features"></a><code>--all-features</code></dt> 75<dd class="option-desc">Activate all available features of all selected packages.</dd> 76 77 78<dt class="option-term" id="option-cargo-run---no-default-features"><a class="option-anchor" href="#option-cargo-run---no-default-features"></a><code>--no-default-features</code></dt> 79<dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> 80 81 82</dl> 83 84 85### Compilation Options 86 87<dl> 88 89<dt class="option-term" id="option-cargo-run---target"><a class="option-anchor" href="#option-cargo-run---target"></a><code>--target</code> <em>triple</em></dt> 90<dd class="option-desc">Run for the given architecture. The default is the host 91architecture. The general format of the triple is 92<code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a 93list of supported targets.</p> 94<p>This may also be specified with the <code>build.target</code> 95<a href="../reference/config.html">config value</a>.</p> 96<p>Note that specifying this flag makes Cargo run in a different mode where the 97target artifacts are placed in a separate directory. See the 98<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> 99 100 101 102<dt class="option-term" id="option-cargo-run---release"><a class="option-anchor" href="#option-cargo-run---release"></a><code>--release</code></dt> 103<dd class="option-desc">Run optimized artifacts with the <code>release</code> profile. 104See also the <code>--profile</code> option for choosing a specific profile by name.</dd> 105 106 107 108<dt class="option-term" id="option-cargo-run---profile"><a class="option-anchor" href="#option-cargo-run---profile"></a><code>--profile</code> <em>name</em></dt> 109<dd class="option-desc">Run with the given profile. 110See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> 111 112 113 114<dt class="option-term" id="option-cargo-run---ignore-rust-version"><a class="option-anchor" href="#option-cargo-run---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> 115<dd class="option-desc">Run the target even if the selected Rust compiler is older than the 116required Rust version as configured in the project's <code>rust-version</code> field.</dd> 117 118 119 120</dl> 121 122### Output Options 123 124<dl> 125<dt class="option-term" id="option-cargo-run---target-dir"><a class="option-anchor" href="#option-cargo-run---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> 126<dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be 127specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the 128<code>build.target-dir</code> <a href="../reference/config.html">config value</a>. 129Defaults to <code>target</code> in the root of the workspace.</dd> 130 131 132</dl> 133 134### Display Options 135 136<dl> 137 138<dt class="option-term" id="option-cargo-run--v"><a class="option-anchor" href="#option-cargo-run--v"></a><code>-v</code></dt> 139<dt class="option-term" id="option-cargo-run---verbose"><a class="option-anchor" href="#option-cargo-run---verbose"></a><code>--verbose</code></dt> 140<dd class="option-desc">Use verbose output. May be specified twice for "very verbose" output which 141includes extra output such as dependency warnings and build script output. 142May also be specified with the <code>term.verbose</code> 143<a href="../reference/config.html">config value</a>.</dd> 144 145 146<dt class="option-term" id="option-cargo-run--q"><a class="option-anchor" href="#option-cargo-run--q"></a><code>-q</code></dt> 147<dt class="option-term" id="option-cargo-run---quiet"><a class="option-anchor" href="#option-cargo-run---quiet"></a><code>--quiet</code></dt> 148<dd class="option-desc">No output printed to stdout.</dd> 149 150 151<dt class="option-term" id="option-cargo-run---color"><a class="option-anchor" href="#option-cargo-run---color"></a><code>--color</code> <em>when</em></dt> 152<dd class="option-desc">Control when colored output is used. Valid values:</p> 153<ul> 154<li><code>auto</code> (default): Automatically detect if color support is available on the 155terminal.</li> 156<li><code>always</code>: Always display colors.</li> 157<li><code>never</code>: Never display colors.</li> 158</ul> 159<p>May also be specified with the <code>term.color</code> 160<a href="../reference/config.html">config value</a>.</dd> 161 162 163 164<dt class="option-term" id="option-cargo-run---message-format"><a class="option-anchor" href="#option-cargo-run---message-format"></a><code>--message-format</code> <em>fmt</em></dt> 165<dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times 166and consists of comma-separated values. Valid values:</p> 167<ul> 168<li><code>human</code> (default): Display in a human-readable text format. Conflicts with 169<code>short</code> and <code>json</code>.</li> 170<li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> 171and <code>json</code>.</li> 172<li><code>json</code>: Emit JSON messages to stdout. See 173<a href="../reference/external-tools.html#json-messages">the reference</a> 174for more details. Conflicts with <code>human</code> and <code>short</code>.</li> 175<li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains 176the "short" rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> 177<li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages 178contains embedded ANSI color codes for respecting rustc's default color 179scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> 180<li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics in 181in JSON messages printed, but instead Cargo itself should render the 182JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others 183coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> 184</ul></dd> 185 186 187 188</dl> 189 190### Manifest Options 191 192<dl> 193 194<dt class="option-term" id="option-cargo-run---manifest-path"><a class="option-anchor" href="#option-cargo-run---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> 195<dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the 196<code>Cargo.toml</code> file in the current directory or any parent directory.</dd> 197 198 199 200<dt class="option-term" id="option-cargo-run---frozen"><a class="option-anchor" href="#option-cargo-run---frozen"></a><code>--frozen</code></dt> 201<dt class="option-term" id="option-cargo-run---locked"><a class="option-anchor" href="#option-cargo-run---locked"></a><code>--locked</code></dt> 202<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is 203up-to-date. If the lock file is missing, or it needs to be updated, Cargo will 204exit with an error. The <code>--frozen</code> flag also prevents Cargo from 205attempting to access the network to determine if it is out-of-date.</p> 206<p>These may be used in environments where you want to assert that the 207<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network 208access.</dd> 209 210 211<dt class="option-term" id="option-cargo-run---offline"><a class="option-anchor" href="#option-cargo-run---offline"></a><code>--offline</code></dt> 212<dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this 213flag, Cargo will stop with an error if it needs to access the network and 214the network is not available. With this flag, Cargo will attempt to 215proceed without the network if possible.</p> 216<p>Beware that this may result in different dependency resolution than online 217mode. Cargo will restrict itself to crates that are downloaded locally, even 218if there might be a newer version as indicated in the local copy of the index. 219See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going 220offline.</p> 221<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> 222 223 224 225</dl> 226 227### Common Options 228 229<dl> 230 231<dt class="option-term" id="option-cargo-run-+toolchain"><a class="option-anchor" href="#option-cargo-run-+toolchain"></a><code>+</code><em>toolchain</em></dt> 232<dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> 233begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such 234as <code>+stable</code> or <code>+nightly</code>). 235See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> 236for more information about how toolchain overrides work.</dd> 237 238 239<dt class="option-term" id="option-cargo-run--h"><a class="option-anchor" href="#option-cargo-run--h"></a><code>-h</code></dt> 240<dt class="option-term" id="option-cargo-run---help"><a class="option-anchor" href="#option-cargo-run---help"></a><code>--help</code></dt> 241<dd class="option-desc">Prints help information.</dd> 242 243 244<dt class="option-term" id="option-cargo-run--Z"><a class="option-anchor" href="#option-cargo-run--Z"></a><code>-Z</code> <em>flag</em></dt> 245<dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> 246 247 248</dl> 249 250 251### Miscellaneous Options 252 253<dl> 254<dt class="option-term" id="option-cargo-run--j"><a class="option-anchor" href="#option-cargo-run--j"></a><code>-j</code> <em>N</em></dt> 255<dt class="option-term" id="option-cargo-run---jobs"><a class="option-anchor" href="#option-cargo-run---jobs"></a><code>--jobs</code> <em>N</em></dt> 256<dd class="option-desc">Number of parallel jobs to run. May also be specified with the 257<code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to 258the number of CPUs.</dd> 259 260 261</dl> 262 263## ENVIRONMENT 264 265See [the reference](../reference/environment-variables.html) for 266details on environment variables that Cargo reads. 267 268 269## EXIT STATUS 270 271* `0`: Cargo succeeded. 272* `101`: Cargo failed to complete. 273 274 275## EXAMPLES 276 2771. Build the local package and run its main target (assuming only one binary): 278 279 cargo run 280 2812. Run an example with extra arguments: 282 283 cargo run --example exname -- --exoption exarg1 exarg2 284 285## SEE ALSO 286[cargo(1)](cargo.html), [cargo-build(1)](cargo-build.html) 287