{"id":"90c306aa2c55ec4b","repo":"rust-lang/cargo","slug":"running-the-file-cmd-requires-zscript","errorCode":null,"errorMessage":"running the file `{cmd}` requires `-Zscript`","messagePattern":"running the file `(.+?)` requires `-Zscript`","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/bin/cargo/commands/run.rs","lineNumber":102,"sourceCode":"            };\n        }\n    };\n\n    ops::run(&ws, &compile_opts, &values_os(args, \"args\")).map_err(|err| to_run_error(gctx, err))\n}\n\n/// See also `util/toml/mod.rs`s `is_embedded`\npub fn is_manifest_command(arg: &str) -> bool {\n    let path = Path::new(arg);\n    1 < path.components().count() || path.extension() == Some(OsStr::new(\"rs\"))\n}\n\npub fn exec_manifest_command(gctx: &mut GlobalContext, cmd: &str, args: &[OsString]) -> CliResult {\n    let manifest_path = Path::new(cmd);\n    match (manifest_path.is_file(), gctx.cli_unstable().script) {\n        (true, true) => {}\n        (true, false) => {\n            return Err(anyhow::anyhow!(\"running the file `{cmd}` requires `-Zscript`\").into());\n        }\n        (false, true) => {\n            let possible_commands = crate::list_commands(gctx);\n            let is_dir = if manifest_path.is_dir() {\n                format!(\": `{cmd}` is a directory\")\n            } else {\n                \"\".to_owned()\n            };\n            let suggested_command = if let Some(suggested_command) = possible_commands\n                .keys()\n                .filter(|c| cmd.starts_with(c.as_str()))\n                .max_by_key(|c| c.len())\n            {\n                let actual_args = cmd.strip_prefix(suggested_command).unwrap();\n                let args = if args.is_empty() {\n                    \"\".to_owned()\n                } else {\n                    format!(","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/rust-lang/cargo/blob/0e07a155371a6ce88ae53a2c00df940280c09a67/src/bin/cargo/commands/run.rs#L84-L120","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["On nightly, enable the feature: `cargo +nightly -Zscript run script.rs` (or set [unstable] script = true in .cargo/config.toml).","If you did not mean a script, put the file inside a proper package (src/bin or src/main.rs) and run `cargo run`.","Track the -Zscript stabilization status for your Cargo version."],"exampleFix":"// before\ncargo run ./tools/helper.rs\n\n// after\ncargo +nightly -Zscript run ./tools/helper.rs","handlingStrategy":"validation","validationCode":"// Only treat a path as a manifest command when -Zscript is enabled\nfn can_run_manifest_command(path: &str, script_enabled: bool) -> bool {\n    let p = std::path::Path::new(path);\n    let is_script_like = p.extension() == Some(std::ffi::OsStr::new(\"rs\"))\n        || p.components().count() > 1;\n    !is_script_like || script_enabled\n}\n\nif !can_run_manifest_command(arg, unstable_script) {\n    eprintln!(\"running `{arg}` requires nightly + `-Zscript`\");\n}","typeGuard":"fn looks_like_manifest_command(arg: &str) -> bool {\n    let p = std::path::Path::new(arg);\n    p.components().count() > 1 || p.extension() == Some(std::ffi::OsStr::new(\"rs\"))\n}","tryCatchPattern":null,"preventionTips":["Enable -Zscript on nightly when running single-file scripts.","Otherwise keep binaries inside a normal package (src/bin) and `cargo run` them.","Track -Zscript stabilization to know when the flag is no longer needed."],"tags":["cargo","run","script","nightly","unstable","cli"],"analyzedSha":"0e07a155371a6ce88ae53a2c00df940280c09a67","analyzedAt":"2026-08-06T01:46:58.334Z","schemaVersion":2}