rust-lang/cargo · error

running the file `{cmd}` requires `-Zscript`

Error message

running the file `{cmd}` requires `-Zscript`

What it means

From exec_manifest_command (src/bin/cargo/commands/run.rs:97-103). When an argument looks like a manifest command (a path that is a file, or has >1 component / an .rs extension), Cargo checks gctx.cli_unstable().script. If the file exists but the -Zscript unstable flag is not enabled, it bails: running a file (e.g. a single-file cargo script) requires the nightly -Zscript feature.

Source

Thrown at src/bin/cargo/commands/run.rs:102

            };
        }
    };

    ops::run(&ws, &compile_opts, &values_os(args, "args")).map_err(|err| to_run_error(gctx, err))
}

/// See also `util/toml/mod.rs`s `is_embedded`
pub fn is_manifest_command(arg: &str) -> bool {
    let path = Path::new(arg);
    1 < path.components().count() || path.extension() == Some(OsStr::new("rs"))
}

pub fn exec_manifest_command(gctx: &mut GlobalContext, cmd: &str, args: &[OsString]) -> CliResult {
    let manifest_path = Path::new(cmd);
    match (manifest_path.is_file(), gctx.cli_unstable().script) {
        (true, true) => {}
        (true, false) => {
            return Err(anyhow::anyhow!("running the file `{cmd}` requires `-Zscript`").into());
        }
        (false, true) => {
            let possible_commands = crate::list_commands(gctx);
            let is_dir = if manifest_path.is_dir() {
                format!(": `{cmd}` is a directory")
            } else {
                "".to_owned()
            };
            let suggested_command = if let Some(suggested_command) = possible_commands
                .keys()
                .filter(|c| cmd.starts_with(c.as_str()))
                .max_by_key(|c| c.len())
            {
                let actual_args = cmd.strip_prefix(suggested_command).unwrap();
                let args = if args.is_empty() {
                    "".to_owned()
                } else {
                    format!(

View on GitHub (pinned to 0e07a15537)

Solutions

1. On nightly, enable the feature: `cargo +nightly -Zscript run script.rs` (or set [unstable] script = true in .cargo/config.toml).
2. If you did not mean a script, put the file inside a proper package (src/bin or src/main.rs) and run `cargo run`.
3. Track the -Zscript stabilization status for your Cargo version.

Example fix

// before
cargo run ./tools/helper.rs

// after
cargo +nightly -Zscript run ./tools/helper.rs

// Only treat a path as a manifest command when -Zscript is enabled
fn can_run_manifest_command(path: &str, script_enabled: bool) -> bool {
    let p = std::path::Path::new(path);
    let is_script_like = p.extension() == Some(std::ffi::OsStr::new("rs"))
        || p.components().count() > 1;
    !is_script_like || script_enabled
}

if !can_run_manifest_command(arg, unstable_script) {
    eprintln!("running `{arg}` requires nightly + `-Zscript`");
}

fn looks_like_manifest_command(arg: &str) -> bool {
    let p = std::path::Path::new(arg);
    p.components().count() > 1 || p.extension() == Some(std::ffi::OsStr::new("rs"))
}

When it happens

Trigger: `cargo run script.rs` (or `cargo script.rs args`) on stable Cargo, or nightly without -Zscript. The path is an existing file but the script feature gate is off.

Common situations: Trying the single-file package (RFC 3502) on stable before stabilization; nightly users who forgot the -Zscript flag; invoking a `.rs` file directly expecting cargo-script behavior.

Related errors

• no such file or subcommand `{cmd}`{is_dir}{suggested_command
• not implemented
• `cargo run` does not support glob pattern `{}` on package se
• `--edges public` requires `-Zunstable-options`
• parsing `{}` requires `-Zscript`

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/90c306aa2c55ec4b.json. Report an issue: GitHub.