feat: Support remote scripts with uv run

crates/uv-cli/src/lib.rs

@@ -1,5 +1,5 @@
 use std::ffi::OsString;
-use std::ops::Deref;
+use std::ops::{Deref, DerefMut};
 use std::path::PathBuf;
 use std::str::FromStr;
 
@@ -600,12 +600,13 @@ pub enum ProjectCommand {
     ///
     /// Ensures that the command runs in a Python environment.
     ///
-    /// When used with a file ending in `.py`, the file will be treated as a
-    /// script and run with a Python interpreter, i.e., `uv run file.py` is
-    /// equivalent to `uv run python file.py`. If the script contains inline
-    /// dependency metadata, it will be installed into an isolated, ephemeral
-    /// environment. When used with `-`, the input will be read from stdin,
-    /// and treated as a Python script.
+    /// When used with a file ending in `.py` or an HTTP(S) URL, the file
+    /// will be treated as a script and run with a Python interpreter,
+    /// i.e., `uv run file.py` is equivalent to `uv run python file.py`.
+    /// For URLs, the script is temporarily downloaded before execution. If
+    /// the script contains inline dependency metadata, it will be installed
+    /// into an isolated, ephemeral environment. When used with `-`, the
+    /// input will be read from stdin, and treated as a Python script.
     ///
     /// When used in a project, the project environment will be created and
     /// updated before invoking the command.
@@ -2305,6 +2306,14 @@ impl Deref for ExternalCommand {
     }
 }
 
+impl DerefMut for ExternalCommand {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        match self {
+            Self::Cmd(cmd) => cmd,
+        }
+    }
+}
+
 impl ExternalCommand {
     pub fn split(&self) -> (Option<&OsString>, &[OsString]) {
         match self.as_slice() {

crates/uv/Cargo.toml

@@ -71,6 +71,7 @@ miette = { workspace = true, features = ["fancy-no-backtrace"] }
 owo-colors = { workspace = true }
 rayon = { workspace = true }
 regex = { workspace = true }
+reqwest = { workspace = true }
 rustc-hash = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }

crates/uv/src/lib.rs

@@ -18,10 +18,12 @@ use uv_cli::{
     compat::CompatArgs, BuildBackendCommand, CacheCommand, CacheNamespace, Cli, Commands,
     PipCommand, PipNamespace, ProjectCommand,
 };
-use uv_cli::{PythonCommand, PythonNamespace, ToolCommand, ToolNamespace, TopLevelArgs};
+use uv_cli::{
+    ExternalCommand, PythonCommand, PythonNamespace, ToolCommand, ToolNamespace, TopLevelArgs,
+};
 #[cfg(feature = "self-update")]
 use uv_cli::{SelfCommand, SelfNamespace, SelfUpdateArgs};
-use uv_fs::CWD;
+use uv_fs::{write_atomic, CWD};
 use uv_requirements::RequirementsSource;
 use uv_scripts::Pep723Script;
 use uv_settings::{Combine, FilesystemOptions, Options};
@@ -42,8 +44,54 @@ pub(crate) mod printer;
 pub(crate) mod settings;
 pub(crate) mod version;
 
+/// Resolves the script target for a run command.
+///
+/// If it's a local file, does nothing. If it's a URL, downloads the content
+/// to a temporary file and updates the command. Prioritizes local files over URLs.
+/// Returns Some(NamedTempFile) if a remote script was downloaded, None otherwise.
+async fn resolve_script_target(
+    command: &mut ExternalCommand,
+) -> Result<Option<tempfile::NamedTempFile>> {
+    let Some(target) = command.get_mut(0) else {
+        return Ok(None);
+    };
+
+    // Only continue if we are absolutely certain no local file exists.
+    //
+    // We don't do this check on Windows since the file path would
+    // be invalid anyway, and thus couldn't refer to a local file.
+    if cfg!(unix) && !matches!(Path::new(target).try_exists(), Ok(false)) {
+        return Ok(None);
+    }
+
+    let maybe_url = target.to_string_lossy();
+
+    // Only continue if the target truly looks like a URL.
+    if !(maybe_url.starts_with("http://") || maybe_url.starts_with("https://")) {
+        return Ok(None);
+    }
+
+    let script_url = url::Url::parse(&maybe_url)?;
+    let file_stem = script_url
+        .path_segments()
+        .and_then(std::iter::Iterator::last)
+        .and_then(|segment| segment.strip_suffix(".py"))
+        .unwrap_or("script");
+
+    let temp_file = tempfile::Builder::new()
+        .prefix(file_stem)
+        .suffix(".py")
+        .tempfile()?;
+
+    let response = reqwest::get(script_url).await?;
+    let contents = response.bytes().await?;
+    write_atomic(&temp_file, &contents).await?;
+    *target = temp_file.path().into();
+    Ok(Some(temp_file))
+}
+
 #[instrument(skip_all)]
-async fn run(cli: Cli) -> Result<ExitStatus> {
+async fn run(mut cli: Cli) -> Result<ExitStatus> {
     // Enable flag to pick up warnings generated by workspace loading.
     if !cli.top_level.global_args.quiet {
         uv_warnings::enable();
@@ -130,11 +178,13 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
     };
 
     // Parse the external command, if necessary.
-    let run_command = if let Commands::Project(command) = &*cli.command {
+    let mut maybe_tempfile: Option<tempfile::NamedTempFile> = None;
+    let run_command = if let Commands::Project(command) = &mut *cli.command {
         if let ProjectCommand::Run(uv_cli::RunArgs {
             command, module, ..
-        }) = &**command
+        }) = &mut **command
         {
+            maybe_tempfile = resolve_script_target(command).await?;
             Some(RunCommand::from_args(command, *module)?)
         } else {
             None
@@ -208,6 +258,15 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
         Printer::Default
     };
 
+    // We only have a tempfile if we downloaded a remote script.
+    if let Some(temp_file) = maybe_tempfile.as_ref() {
+        writeln!(
+            printer.stderr(),
+            "Downloaded remote script to: {}",
+            temp_file.path().display().cyan(),
+        )?;
+    }
+
     // Configure the `warn!` macros, which control user-facing warnings in the CLI.
     if globals.quiet {
         uv_warnings::disable();
@@ -255,7 +314,7 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
     // Configure the cache.
     let cache = Cache::from_settings(cache_settings.no_cache, cache_settings.cache_dir)?;
 
-    match *cli.command {
+    let result = match *cli.command {
         Commands::Help(args) => commands::help(
             args.command.unwrap_or_default().as_slice(),
             printer,
@@ -1144,7 +1203,9 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
                 commands::build_backend::prepare_metadata_for_build_editable(&wheel_directory)
             }
         },
-    }
+    };
+    drop(maybe_tempfile);
+    result
 }
 
 /// Run a [`ProjectCommand`].

crates/uv/tests/run.rs

@@ -2164,3 +2164,63 @@ fn run_script_without_build_system() -> Result<()> {
 
     Ok(())
 }
+
+#[test]
+fn run_remote_pep723_script() {
+    let context = TestContext::new("3.12").with_filtered_python_names();
+    let mut filters = context.filters();
+    filters.push((
+        r"(?m)^Reading inline script metadata from:.*\.py$",
+        "Reading inline script metadata from: [TEMP_PATH].py",
+    ));
+    filters.push((
+        r"(?m)^Downloaded remote script to:.*\.py$",
+        "Downloaded remote script to: [TEMP_PATH].py",
+    ));
+    uv_snapshot!(filters, context.run().arg("https://raw.githubusercontent.com/astral-sh/uv/df45b9ac2584824309ff29a6a09421055ad730f6/scripts/uv-run-remote-script-test.py").arg("CI"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    Hello CI, from uv!
+
+    ----- stderr -----
+    Downloaded remote script to: [TEMP_PATH].py
+    Reading inline script metadata from: [TEMP_PATH].py
+    Resolved 4 packages in [TIME]
+    Prepared 4 packages in [TIME]
+    Installed 4 packages in [TIME]
+     + markdown-it-py==3.0.0
+     + mdurl==0.1.2
+     + pygments==2.17.2
+     + rich==13.7.1
+    "###);
+}
+
+#[cfg(unix)] // A URL could be a valid filepath on Unix but not on Windows
+#[test]
+fn run_url_like_with_local_file_priority() -> Result<()> {
+    let context = TestContext::new("3.12");
+
+    let url = "https://example.com/path/to/main.py";
+    let local_path: std::path::PathBuf = ["https:", "", "example.com", "path", "to", "main.py"]
+        .iter()
+        .collect();
+
+    // replace with URL-like filepath
+    let test_script = context.temp_dir.child(local_path);
+    test_script.write_str(indoc! { r#"
+        print("Hello, world!")
+       "#
+    })?;
+
+    uv_snapshot!(context.filters(), context.run().arg(url), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    Hello, world!
+
+    ----- stderr -----
+    "###);
+
+    Ok(())
+}

docs/reference/cli.md

@@ -54,7 +54,7 @@ Run a command or script.
 
 Ensures that the command runs in a Python environment.
 
-When used with a file ending in `.py`, the file will be treated as a script and run with a Python interpreter, i.e., `uv run file.py` is equivalent to `uv run python file.py`. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with `-`, the input will be read from stdin, and treated as a Python script.
+When used with a file ending in `.py` or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter, i.e., `uv run file.py` is equivalent to `uv run python file.py`. For URLs, the script is temporarily downloaded before execution. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with `-`, the input will be read from stdin, and treated as a Python script.
 
 When used in a project, the project environment will be created and updated before invoking the command.