{"record":{"id":"f7757883a9b40ec4","repo":"denoland/deno","slug":"use-deno-run-to-run-a-local-file-directly-deno","errorCode":null,"errorMessage":"Use 'deno run' to run a local file directly, 'deno x' is intended for running commands from packages.","messagePattern":"Use 'deno run' to run a local file directly, 'deno x' is intended for running commands from packages\\.","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"cli/tools/x.rs","lineNumber":611,"sourceCode":"  }\n\n  // When --package is specified, the command is the binary name and\n  // the package flag specifies which package to install. Combine them\n  // into a single specifier like \"npm:package/binary\" so the existing\n  // resolution flow handles it correctly.\n  let effective_command = if let Some(ref package) = command_flags.package {\n    format!(\"{}/{}\", package, command_flags.command)\n  } else {\n    command_flags.command.clone()\n  };\n\n  let is_file_like = effective_command.starts_with('.')\n    || effective_command.starts_with('/')\n    || effective_command.starts_with('~')\n    || effective_command.starts_with('\\\\')\n    || Path::new(&effective_command).extension().is_some();\n  if is_file_like && Path::new(&effective_command).is_file() {\n    return Err(anyhow::anyhow!(\n      \"Use 'deno run' to run a local file directly, 'deno x' is intended for running commands from packages.\"\n    ));\n  }\n\n  let thing_to_run = match deno_core::url::Url::parse(&effective_command) {\n    Ok(url) => {\n      if url.scheme() == \"npm\" {\n        let req_ref = NpmPackageReqReference::from_specifier(&url)?;\n        ReqRefOrUrl::Npm(req_ref)\n      } else if url.scheme() == \"jsr\" {\n        let req_ref = JsrPackageReqReference::from_specifier(&url)?;\n        ReqRefOrUrl::Jsr(req_ref)\n      } else {\n        ReqRefOrUrl::Url(url)\n      }\n    }\n    Err(deno_core::url::ParseError::RelativeUrlWithoutBase) => {\n      let new_command = format!(\"npm:{}\", effective_command);","sourceCodeStart":593,"sourceCodeEnd":629,"githubUrl":"https://github.com/denoland/deno/blob/89f33cbef296a2b287f323d42de54c871fa69c77/cli/tools/x.rs#L593-L629","documentation":"`deno x` executes commands from packages, not local files. If the command string looks file-like (starts with '.', '/', '~', or '\\\\', or has a file extension) and that path exists as a file on disk, deno refuses to run it and redirects to `deno run`.","triggerScenarios":"`deno x ./script.ts`, `deno x ~/tool.ts`, or `deno x main.ts` where the path exists as a file at launch time.","commonSituations":"Muscle memory from npx/bunx, which can execute local files; typos such as `deno x run mod.ts` where 'run mod.ts' is misread as one file-like token.","solutions":["Use `deno run` for local files (add permission flags as needed): `deno run ./script.ts`","If a package command was intended, use explicit package syntax: `deno x npm:cowsay hello` or `deno x <pkg>/<bin>`","For a local executable whose name contains a dot, rename it so the command is not file-like"],"exampleFix":"# before\ndeno x ./script.ts\n# after\ndeno run --allow-all ./script.ts","handlingStrategy":"validation","validationCode":"# bash: route file-like commands to deno run\ncmd=\"$1\"\nif [[ \"$cmd\" == .* || \"$cmd\" == /* || \"$cmd\" == ~* || \"$cmd\" == *.* ]] && [ -f \"$cmd\" ]; then\n  exec deno run \"$@\"\nfi\nexec deno x \"$@\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use `deno run` for anything on disk; reserve `deno x` for package commands","Write wrappers that route on path-shaped arguments before calling deno x","Remember npx-style local execution does not apply to deno x"],"tags":["cli","deno-x","usage","local-files"],"backgroundTag":null,"analyzedSha":"89f33cbef296a2b287f323d42de54c871fa69c77","analyzedAt":"2026-08-16T07:54:21.310Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}