Support pylock.toml in --with-requirements in uv run and uvx

crates/uv/src/commands/project/environment.rs

@@ -1,12 +1,14 @@
 use std::path::Path;
 
 use tracing::debug;
+use uv_warnings::warn_user;
 
 use crate::commands::pip::loggers::{InstallLogger, ResolveLogger};
 use crate::commands::pip::operations::Modifications;
 use crate::commands::project::{
     EnvironmentSpecification, PlatformState, ProjectError, resolve_environment, sync_environment,
 };
+use crate::commands::pylock::{read_pylock_toml, resolve_pylock_toml};
 use crate::printer::Printer;
 use crate::settings::ResolverInstallerSettings;
 
@@ -19,7 +21,7 @@ use uv_distribution_types::{
     BuiltDist, Dist, Identifier, Node, Resolution, ResolvedDist, SourceDist,
 };
 use uv_fs::PythonExt;
-use uv_preview::Preview;
+use uv_preview::{Preview, PreviewFeature};
 use uv_python::{Interpreter, PythonEnvironment, canonicalize_executable};
 use uv_types::SourceTreeEditablePolicy;
 use uv_workspace::WorkspaceCache;
@@ -136,26 +138,52 @@ impl CachedEnvironment {
     ) -> Result<Self, ProjectError> {
         let interpreter = Self::base_interpreter(interpreter, cache)?;
 
-        // Resolve the requirements with the interpreter.
-        let resolution = Resolution::from(
-            resolve_environment(
-                spec,
+        // If a `pylock.toml` was provided, derive the [`Resolution`] from it directly, bypassing
+        // the resolver; otherwise, resolve the requirements with the interpreter.
+        let (resolution, pylock_hasher) = if let Some(pylock) = spec.requirements.pylock.clone() {
+            if !preview.is_enabled(PreviewFeature::Pylock) {
+                warn_user!(
+                    "The `pylock.toml` format is experimental and may change without warning. Pass `--preview-features {}` to disable this warning.",
+                    PreviewFeature::Pylock
+                );
+            }
+            let (install_path, lock) = read_pylock_toml(&pylock, client_builder)
+                .await
+                .map_err(ProjectError::Anyhow)?;
+            let (resolution, hasher) = resolve_pylock_toml(
+                lock,
+                &install_path,
                 &interpreter,
+                None,
                 python_platform,
-                SourceTreeEditablePolicy::Project,
-                build_constraints.clone(),
-                &settings.resolver,
-                client_builder,
-                state,
-                resolve,
-                concurrency,
-                cache,
-                workspace_cache,
-                printer,
-                preview,
+                &[],
+                &[],
+                &settings.resolver.build_options,
             )
-            .await?,
-        );
+            .map_err(ProjectError::Anyhow)?;
+            (resolution, Some(hasher))
+        } else {
+            let resolution = Resolution::from(
+                resolve_environment(
+                    spec,
+                    &interpreter,
+                    python_platform,
+                    SourceTreeEditablePolicy::Project,
+                    build_constraints.clone(),
+                    &settings.resolver,
+                    client_builder,
+                    state,
+                    resolve,
+                    concurrency,
+                    cache,
+                    workspace_cache,
+                    printer,
+                    preview,
+                )
+                .await?,
+            );
+            (resolution, None)
+        };
 
         // Hash the resolution by hashing the generated lockfile.
         let resolution_hash = {
@@ -228,6 +256,7 @@ impl CachedEnvironment {
         sync_environment(
             venv,
             &resolution,
+            pylock_hasher.as_ref(),
             Modifications::Exact,
             build_constraints,
             settings.into(),

crates/uv/src/commands/project/mod.rs

@@ -2211,6 +2211,7 @@ pub(crate) async fn resolve_environment(
 pub(crate) async fn sync_environment(
     venv: PythonEnvironment,
     resolution: &Resolution,
+    hasher: Option<&HashStrategy>,
     modifications: Modifications,
     build_constraints: Constraints,
     settings: InstallerSettingsRef<'_>,
@@ -2270,7 +2271,8 @@ pub(crate) async fn sync_environment(
     // optional on the downstream APIs.
     let build_hasher = HashStrategy::default();
     let dry_run = DryRun::default();
-    let hasher = HashStrategy::default();
+    let default_hasher = HashStrategy::default();
+    let hasher = hasher.unwrap_or(&default_hasher);
     let workspace_cache = WorkspaceCache::default();
 
     // Resolve the flat indexes from `--find-links`.
@@ -2279,7 +2281,7 @@ pub(crate) async fn sync_environment(
         let entries = client
             .fetch_all(index_locations.flat_indexes().map(Index::url))
             .await?;
-        FlatIndex::from_entries(entries, Some(tags), &hasher, build_options)
+        FlatIndex::from_entries(entries, Some(tags), hasher, build_options)
     };
 
     // Lower the extra build dependencies, if any.
@@ -2324,7 +2326,7 @@ pub(crate) async fn sync_environment(
         build_options,
         link_mode,
         compile_bytecode,
-        &hasher,
+        hasher,
         tags,
         &client,
         state.in_flight(),

crates/uv/src/commands/project/run.rs

@@ -1378,6 +1378,12 @@ fn can_skip_ephemeral(
         return false;
     }
 
+    // A `pylock.toml` provides a pre-computed set of packages that must be installed into
+    // the ephemeral environment, independent of `spec.requirements`.
+    if spec.pylock.is_some() {
+        return false;
+    }
+
     // Determine the markers and tags to use for resolution.
     let markers = interpreter.resolver_marker_environment();
     let Ok(tags) = interpreter.tags() else {

crates/uv/src/commands/pylock.rs

@@ -1,5 +1,5 @@
 //! Shared helpers for reading `pylock.toml` (PEP 751) files and deriving a [`Resolution`] and
-//! verifying [`HashStrategy`] from them, used by `uv pip install` and `uv pip sync`.
+//! verifying [`HashStrategy`] from them.
 
 use std::path::{Path, PathBuf};
 

crates/uv/src/commands/tool/install.rs

@@ -722,6 +722,7 @@ pub(crate) async fn install(
         match sync_environment(
             environment,
             &resolution.into(),
+            None,
             Modifications::Exact,
             Constraints::from_requirements(build_constraints.iter().cloned()),
             (&settings).into(),

crates/uv/src/commands/tool/upgrade.rs

@@ -370,6 +370,7 @@ async fn upgrade_tool(
         let environment = sync_environment(
             environment,
             &resolution.into(),
+            None,
             Modifications::Exact,
             build_constraints,
             (&settings).into(),

crates/uv/tests/it/run.rs

@@ -3068,6 +3068,85 @@ fn run_requirements_txt_arguments() -> Result<()> {
     Ok(())
 }
 
+/// Read `--with-requirements` from a `pylock.toml` file.
+#[test]
+fn run_pylock_toml() -> Result<()> {
+    let context = uv_test::test_context!("3.12");
+
+    // Create the base project.
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(indoc! { r#"
+        [project]
+        name = "foo"
+        version = "1.0.0"
+        requires-python = ">=3.12"
+        dependencies = ["sniffio"]
+
+        [build-system]
+        requires = ["uv_build>=0.7,<10000"]
+        build-backend = "uv_build"
+        "#
+    })?;
+    context
+        .temp_dir
+        .child("src")
+        .child("foo")
+        .child("__init__.py")
+        .touch()?;
+
+    let main_py = context.temp_dir.child("main.py");
+    main_py.write_str(indoc! { r"
+        import iniconfig
+        import sniffio
+       "
+    })?;
+
+    // Create a secondary project whose lockfile we'll export to a `pylock.toml`.
+    let locked = context.temp_dir.child("locked");
+    locked.child("pyproject.toml").write_str(indoc! { r#"
+        [project]
+        name = "locked"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = ["iniconfig"]
+        "#
+    })?;
+
+    context
+        .export()
+        .arg("--project")
+        .arg("locked")
+        .arg("-o")
+        .arg("pylock.toml")
+        .assert()
+        .success();
+
+    // `iniconfig` is installed into the ephemeral `--with` environment from the `pylock.toml`,
+    // layered on top of the base project env.
+    uv_snapshot!(context.filters(), context.run()
+        .arg("--preview-features")
+        .arg("pylock")
+        .arg("--with-requirements")
+        .arg("pylock.toml")
+        .arg("main.py"), @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 2 packages in [TIME]
+    Prepared 2 packages in [TIME]
+    Installed 2 packages in [TIME]
+     + foo==1.0.0 (from file://[TEMP_DIR]/)
+     + sniffio==1.3.1
+    Prepared 1 package in [TIME]
+    Installed 1 package in [TIME]
+     + iniconfig==2.0.0
+    ");
+
+    Ok(())
+}
+
 /// Ensure that we can import from the root project when layering `--with` requirements.
 #[test]
 fn run_editable() -> Result<()> {

crates/uv/tests/it/tool_run.rs

@@ -1282,6 +1282,62 @@ fn tool_run_requirements_txt_arguments() {
     ");
 }
 
+/// Read requirements from a `pylock.toml` file via `--with-requirements`.
+#[test]
+fn tool_run_pylock_toml() -> Result<()> {
+    let context = uv_test::test_context!("3.12").with_filtered_counts();
+    let tool_dir = context.temp_dir.child("tools");
+    let bin_dir = context.temp_dir.child("bin");
+
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(indoc! {r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = ["flask"]
+    "#})?;
+
+    context
+        .export()
+        .arg("-o")
+        .arg("pylock.toml")
+        .assert()
+        .success();
+
+    // The full set of locked dependencies (Flask and its transitive dependencies) is installed
+    // from the `pylock.toml`, bypassing the resolver.
+    uv_snapshot!(context.filters(), context.tool_run()
+        .arg("--preview-features")
+        .arg("pylock")
+        .arg("--with-requirements")
+        .arg("pylock.toml")
+        .arg("flask")
+        .arg("--version")
+        .env(EnvVars::UV_TOOL_DIR, tool_dir.as_os_str())
+        .env(EnvVars::XDG_BIN_HOME, bin_dir.as_os_str()), @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    Python 3.12.[X]
+    Flask 3.0.2
+    Werkzeug 3.0.1
+
+    ----- stderr -----
+    Prepared [N] packages in [TIME]
+    Installed [N] packages in [TIME]
+     + blinker==1.7.0
+     + click==8.1.7
+     + flask==3.0.2
+     + itsdangerous==2.1.2
+     + jinja2==3.1.3
+     + markupsafe==2.1.5
+     + werkzeug==3.0.1
+    ");
+
+    Ok(())
+}
+
 /// List installed tools when no command arg is given (e.g. `uv tool run`).
 #[test]
 fn tool_run_list_installed() {