1CARGO-RUN(1) General Commands Manual CARGO-RUN(1)
2
6 cargo-run — Run the current package
7
9 cargo run [options] [-- args]
10
12 Run a binary or example of the local package.
13 All the arguments following the two dashes (--) are passed to the
15 binary to run. If you’re passing arguments to both Cargo and the
16 binary, the ones after -- go to the binary, the ones before go to
17 Cargo.
18 Unlike cargo-test(1) and cargo-bench(1), cargo run sets the working
20 directory of the binary executed to the current working directory, same
21 as if it was executed in the shell directly.
22
24 Package Selection
25 By default, the package in the current working directory is selected.
26 The -p flag can be used to choose a different package in a workspace.
27 -p spec, --package spec
29 The package to run. See cargo-pkgid(1) for the SPEC format.
30 Target Selection
32 When no target selection options are given, cargo run will run the
33 binary target. If there are multiple binary targets, you must pass a
34 target flag to choose one. Or, the default-run field may be specified
35 in the [package] section of Cargo.toml to choose the name of the binary
36 to run by default.
37 --bin name
39 Run the specified binary.
40 --example name
42 Run the specified example.
43 Feature Selection
45 The feature flags allow you to control which features are enabled. When
46 no feature options are given, the default feature is activated for
47 every selected package.
48 See the features documentation
50 <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
51 for more details.
52 -F features, --features features
54 Space or comma separated list of features to activate. Features of
55 workspace members may be enabled with package-name/feature-name
56 syntax. This flag may be specified multiple times, which enables
57 all specified features.
58 --all-features
60 Activate all available features of all selected packages.
61 --no-default-features
63 Do not activate the default feature of the selected packages.
64 Compilation Options
66 --target triple
67 Run for the given architecture. The default is the host
68 architecture. The general format of the triple is
69 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
70 a list of supported targets.
71 This may also be specified with the build.target config value
73 <https://doc.rust-lang.org/cargo/reference/config.html>.
74 Note that specifying this flag makes Cargo run in a different mode
76 where the target artifacts are placed in a separate directory. See
77 the build cache
78 <https://doc.rust-lang.org/cargo/guide/build-cache.html>
79 documentation for more details.
80 -r, --release
82 Run optimized artifacts with the release profile. See also the
83 --profile option for choosing a specific profile by name.
84 --profile name
86 Run with the given profile. See the the reference
87 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
88 details on profiles.
89 --ignore-rust-version
91 Run the target even if the selected Rust compiler is older than the
92 required Rust version as configured in the project’s rust-version
93 field.
94 --timings=fmts
96 Output information how long each compilation takes, and track
97 concurrency information over time. Accepts an optional
98 comma-separated list of output formats; --timings without an
99 argument will default to --timings=html. Specifying an output
100 format (rather than the default) is unstable and requires
101 -Zunstable-options. Valid output formats:
102 • html (unstable, requires -Zunstable-options): Write a
104 human-readable file cargo-timing.html to the
105 target/cargo-timings directory with a report of the
106 compilation. Also write a report to the same directory with a
107 timestamp in the filename if you want to look at older runs.
108 HTML output is suitable for human consumption only, and does
109 not provide machine-readable timing data.
110 • json (unstable, requires -Zunstable-options): Emit
112 machine-readable JSON information about timing information.
113 Output Options
115 --target-dir directory
116 Directory for all generated artifacts and intermediate files. May
117 also be specified with the CARGO_TARGET_DIR environment variable,
118 or the build.target-dir config value
119 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
120 to target in the root of the workspace.
121 Display Options
123 -v, --verbose
124 Use verbose output. May be specified twice for “very verbose”
125 output which includes extra output such as dependency warnings and
126 build script output. May also be specified with the term.verbose
127 config value
128 <https://doc.rust-lang.org/cargo/reference/config.html>.
129 -q, --quiet
131 Do not print cargo log messages. May also be specified with the
132 term.quiet config value
133 <https://doc.rust-lang.org/cargo/reference/config.html>.
134 --color when
136 Control when colored output is used. Valid values:
137 • auto (default): Automatically detect if color support is
139 available on the terminal.
140 • always: Always display colors.
142 • never: Never display colors.
144 May also be specified with the term.color config value
146 <https://doc.rust-lang.org/cargo/reference/config.html>.
147 --message-format fmt
149 The output format for diagnostic messages. Can be specified
150 multiple times and consists of comma-separated values. Valid
151 values:
152 • human (default): Display in a human-readable text format.
154 Conflicts with short and json.
155 • short: Emit shorter, human-readable text messages. Conflicts
157 with human and json.
158 • json: Emit JSON messages to stdout. See the reference
160 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
161 for more details. Conflicts with human and short.
162 • json-diagnostic-short: Ensure the rendered field of JSON
164 messages contains the “short” rendering from rustc. Cannot be
165 used with human or short.
166 • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
168 messages contains embedded ANSI color codes for respecting
169 rustc’s default color scheme. Cannot be used with human or
170 short.
171 • json-render-diagnostics: Instruct Cargo to not include rustc
173 diagnostics in JSON messages printed, but instead Cargo itself
174 should render the JSON diagnostics coming from rustc. Cargo’s
175 own JSON diagnostics and others coming from rustc are still
176 emitted. Cannot be used with human or short.
177 Manifest Options
179 --manifest-path path
180 Path to the Cargo.toml file. By default, Cargo searches for the
181 Cargo.toml file in the current directory or any parent directory.
182 --frozen, --locked
184 Either of these flags requires that the Cargo.lock file is
185 up-to-date. If the lock file is missing, or it needs to be updated,
186 Cargo will exit with an error. The --frozen flag also prevents
187 Cargo from attempting to access the network to determine if it is
188 out-of-date.
189 These may be used in environments where you want to assert that the
191 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
192 network access.
193 --offline
195 Prevents Cargo from accessing the network for any reason. Without
196 this flag, Cargo will stop with an error if it needs to access the
197 network and the network is not available. With this flag, Cargo
198 will attempt to proceed without the network if possible.
199 Beware that this may result in different dependency resolution than
201 online mode. Cargo will restrict itself to crates that are
202 downloaded locally, even if there might be a newer version as
203 indicated in the local copy of the index. See the cargo-fetch(1)
204 command to download dependencies before going offline.
205 May also be specified with the net.offline config value
207 <https://doc.rust-lang.org/cargo/reference/config.html>.
208 Common Options
210 +toolchain
211 If Cargo has been installed with rustup, and the first argument to
212 cargo begins with +, it will be interpreted as a rustup toolchain
213 name (such as +stable or +nightly). See the rustup documentation
214 <https://rust-lang.github.io/rustup/overrides.html> for more
215 information about how toolchain overrides work.
216 --config KEY=VALUE or PATH
218 Overrides a Cargo configuration value. The argument should be in
219 TOML syntax of KEY=VALUE, or provided as a path to an extra
220 configuration file. This flag may be specified multiple times. See
221 the command-line overrides section
222 <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
223 for more information.
224 -C PATH
226 Changes the current working directory before executing any
227 specified operations. This affects things like where cargo looks by
228 default for the project manifest (Cargo.toml), as well as the
229 directories searched for discovering .cargo/config.toml, for
230 example. This option must appear before the command name, for
231 example cargo -C path/to/my-project build.
232 This option is only available on the nightly channel
234 <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
235 requires the -Z unstable-options flag to enable (see #10098
236 <https://github.com/rust-lang/cargo/issues/10098>).
237 -h, --help
239 Prints help information.
240 -Z flag
242 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
243 details.
244 Miscellaneous Options
246 -j N, --jobs N
247 Number of parallel jobs to run. May also be specified with the
248 build.jobs config value
249 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
250 to the number of logical CPUs. If negative, it sets the maximum
251 number of parallel jobs to the number of logical CPUs plus provided
252 value. If a string default is provided, it sets the value back to
253 defaults. Should not be 0.
254 --keep-going
256 Build as many crates in the dependency graph as possible, rather
257 than aborting the build on the first one that fails to build.
258 For example if the current package depends on dependencies fails
260 and works, one of which fails to build, cargo run -j1 may or may
261 not build the one that succeeds (depending on which one of the two
262 builds Cargo picked to run first), whereas cargo run -j1
263 --keep-going would definitely run both builds, even if the one run
264 first fails.
265
267 See the reference
268 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
269 for details on environment variables that Cargo reads.
270
272 • 0: Cargo succeeded.
273 • 101: Cargo failed to complete.
275
277 1. Build the local package and run its main target (assuming only one
278 binary):
279 cargo run
281 2. Run an example with extra arguments:
283 cargo run --example exname -- --exoption exarg1 exarg2
285
287 cargo(1), cargo-build(1)
288 CARGO-RUN(1)