Support build constraints in uv tool and PEP723 scripts.

crates/uv-cli/src/lib.rs

@@ -4102,6 +4102,15 @@ pub struct ToolRunArgs {
     #[arg(long, short, alias = "constraint", env = EnvVars::UV_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
     pub constraints: Vec<Maybe<PathBuf>>,
 
+    /// Constrain build dependencies using the given requirements files when building source
+    /// distributions.
+    ///
+    /// Constraints files are `requirements.txt`-like files that only control the _version_ of a
+    /// requirement that's installed. However, including a package in a constraints file will _not_
+    /// trigger the installation of that package.
+    #[arg(long, short, alias = "build-constraint", env = EnvVars::UV_BUILD_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
+    pub build_constraints: Vec<Maybe<PathBuf>>,
+
     /// Override versions using the given requirements files.
     ///
     /// Overrides files are `requirements.txt`-like files that force a specific version of a
@@ -4212,6 +4221,15 @@ pub struct ToolInstallArgs {
     #[arg(long, alias = "override", env = EnvVars::UV_OVERRIDE, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
     pub overrides: Vec<Maybe<PathBuf>>,
 
+    /// Constrain build dependencies using the given requirements files when building source
+    /// distributions.
+    ///
+    /// Constraints files are `requirements.txt`-like files that only control the _version_ of a
+    /// requirement that's installed. However, including a package in a constraints file will _not_
+    /// trigger the installation of that package.
+    #[arg(long, short, alias = "build-constraint", env = EnvVars::UV_BUILD_CONSTRAINT, value_delimiter = ' ', value_parser = parse_maybe_file_path)]
+    pub build_constraints: Vec<Maybe<PathBuf>>,
+
     #[command(flatten)]
     pub installer: ResolverInstallerArgs,
 

crates/uv-tool/src/tool.rs

@@ -19,6 +19,8 @@ pub struct Tool {
     constraints: Vec<Requirement>,
     /// The overrides requested by the user during installation.
     overrides: Vec<Requirement>,
+    /// The build constraints requested by the user during installation.
+    build_constraints: Vec<Requirement>,
     /// The Python requested by the user during installation.
     python: Option<String>,
     /// A mapping of entry point names to their metadata.
@@ -28,13 +30,16 @@ pub struct Tool {
 }
 
 #[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "kebab-case")]
 struct ToolWire {
     #[serde(default)]
     requirements: Vec<RequirementWire>,
     #[serde(default)]
     constraints: Vec<Requirement>,
     #[serde(default)]
     overrides: Vec<Requirement>,
+    #[serde(default)]
+    build_constraint_dependencies: Vec<Requirement>,
     python: Option<String>,
     entrypoints: Vec<ToolEntrypoint>,
     #[serde(default)]
@@ -61,6 +66,7 @@ impl From<Tool> for ToolWire {
                 .collect(),
             constraints: tool.constraints,
             overrides: tool.overrides,
+            build_constraint_dependencies: tool.build_constraints,
             python: tool.python,
             entrypoints: tool.entrypoints,
             options: tool.options,
@@ -83,6 +89,7 @@ impl TryFrom<ToolWire> for Tool {
                 .collect(),
             constraints: tool.constraints,
             overrides: tool.overrides,
+            build_constraints: tool.build_constraint_dependencies,
             python: tool.python,
             entrypoints: tool.entrypoints,
             options: tool.options,
@@ -156,6 +163,7 @@ impl Tool {
         requirements: Vec<Requirement>,
         constraints: Vec<Requirement>,
         overrides: Vec<Requirement>,
+        build_constraints: Vec<Requirement>,
         python: Option<String>,
         entrypoints: impl Iterator<Item = ToolEntrypoint>,
         options: ToolOptions,
@@ -166,6 +174,7 @@ impl Tool {
             requirements,
             constraints,
             overrides,
+            build_constraints,
             python,
             entrypoints,
             options,
@@ -248,6 +257,28 @@ impl Tool {
             });
         }
 
+        if !self.build_constraints.is_empty() {
+            table.insert("build-constraint-dependencies", {
+                let build_constraints = self
+                    .build_constraints
+                    .iter()
+                    .map(|r#build_constraint| {
+                        serde::Serialize::serialize(
+                            &r#build_constraint,
+                            toml_edit::ser::ValueSerializer::new(),
+                        )
+                    })
+                    .collect::<Result<Vec<_>, _>>()?;
+
+                let build_constraints = match build_constraints.as_slice() {
+                    [] => Array::new(),
+                    [r#build_constraint] => Array::from_iter([r#build_constraint]),
+                    build_constraints => each_element_on_its_line_array(build_constraints.iter()),
+                };
+                value(build_constraints)
+            });
+        }
+
         if let Some(ref python) = self.python {
             table.insert("python", value(python));
         }
@@ -292,6 +323,10 @@ impl Tool {
         &self.overrides
     }
 
+    pub fn build_constraints(&self) -> &[Requirement] {
+        &self.build_constraints
+    }
+
     pub fn python(&self) -> &Option<String> {
         &self.python
     }

crates/uv/src/commands/build_frontend.rs

@@ -519,8 +519,8 @@ async fn build_package(
 
     let build_constraints = Constraints::from_requirements(
         build_constraints
-            .iter()
-            .map(|constraint| constraint.requirement.clone()),
+            .into_iter()
+            .map(|constraint| constraint.requirement),
     );
 
     // Initialize the registry client.

crates/uv/src/commands/pip/compile.rs

@@ -213,8 +213,7 @@ pub(crate) async fn pip_compile(
     let build_constraints: Vec<NameRequirementSpecification> =
         operations::read_constraints(build_constraints, &client_builder)
             .await?
-            .iter()
-            .cloned()
+            .into_iter()
             .chain(
                 build_constraints_from_workspace
                     .into_iter()

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

@@ -154,8 +154,7 @@ pub(crate) async fn pip_install(
     let build_constraints: Vec<NameRequirementSpecification> =
         operations::read_constraints(build_constraints, &client_builder)
             .await?
-            .iter()
-            .cloned()
+            .into_iter()
             .chain(
                 build_constraints_from_workspace
                     .iter()

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

@@ -2,7 +2,7 @@ use tracing::debug;
 
 use uv_cache::{Cache, CacheBucket};
 use uv_cache_key::{cache_digest, hash_digest};
-use uv_configuration::{Concurrency, PreviewMode};
+use uv_configuration::{Concurrency, Constraints, PreviewMode};
 use uv_distribution_types::{Name, Resolution};
 use uv_python::{Interpreter, PythonEnvironment};
 
@@ -28,6 +28,7 @@ impl CachedEnvironment {
     /// Get or create an [`CachedEnvironment`] based on a given set of requirements.
     pub(crate) async fn from_spec(
         spec: EnvironmentSpecification<'_>,
+        build_constraints: Constraints,
         interpreter: &Interpreter,
         settings: &ResolverInstallerSettings,
         network_settings: &NetworkSettings,
@@ -99,6 +100,7 @@ impl CachedEnvironment {
             venv,
             &resolution,
             Modifications::Exact,
+            build_constraints,
             settings.into(),
             network_settings,
             state,

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

@@ -1824,6 +1824,7 @@ pub(crate) async fn sync_environment(
     venv: PythonEnvironment,
     resolution: &Resolution,
     modifications: Modifications,
+    build_constraints: Constraints,
     settings: InstallerSettingsRef<'_>,
     network_settings: &NetworkSettings,
     state: &PlatformState,
@@ -1891,7 +1892,6 @@ pub(crate) async fn sync_environment(
 
     // TODO(charlie): These are all default values. We should consider whether we want to make them
     // optional on the downstream APIs.
-    let build_constraints = Constraints::default();
     let build_hasher = HashStrategy::default();
     let dry_run = DryRun::default();
     let hasher = HashStrategy::default();
@@ -1982,6 +1982,7 @@ pub(crate) async fn update_environment(
     venv: PythonEnvironment,
     spec: RequirementsSpecification,
     modifications: Modifications,
+    build_constraints: Constraints,
     settings: &ResolverInstallerSettings,
     network_settings: &NetworkSettings,
     state: &SharedState,
@@ -2113,7 +2114,6 @@ pub(crate) async fn update_environment(
 
     // TODO(charlie): These are all default values. We should consider whether we want to make them
     // optional on the downstream APIs.
-    let build_constraints = Constraints::default();
     let build_hasher = HashStrategy::default();
     let extras = ExtrasSpecification::default();
     let groups = BTreeMap::new();

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

@@ -17,9 +17,10 @@ use uv_cache::Cache;
 use uv_cli::ExternalCommand;
 use uv_client::BaseClientBuilder;
 use uv_configuration::{
-    Concurrency, DependencyGroups, DryRun, EditableMode, ExtrasSpecification, InstallOptions,
-    PreviewMode,
+    Concurrency, Constraints, DependencyGroups, DryRun, EditableMode, ExtrasSpecification,
+    InstallOptions, PreviewMode,
 };
+use uv_distribution_types::Requirement;
 use uv_fs::which::is_executable;
 use uv_fs::{PythonExt, Simplified};
 use uv_installer::{SatisfiesResult, SitePackages};
@@ -351,10 +352,28 @@ hint: If you are running a script with `{}` in the shebang, you may need to incl
                 .await?
                 .into_environment()?;
 
+                let build_constraints = script
+                    .metadata()
+                    .tool
+                    .as_ref()
+                    .and_then(|tool| {
+                        tool.uv
+                            .as_ref()
+                            .and_then(|uv| uv.build_constraint_dependencies.as_ref())
+                    })
+                    .map(|constraints| {
+                        Constraints::from_requirements(
+                            constraints
+                                .iter()
+                                .map(|constraint| Requirement::from(constraint.clone())),
+                        )
+                    });
+
                 match update_environment(
                     environment,
                     spec,
                     modifications,
+                    build_constraints.unwrap_or_default(),
                     &settings,
                     &network_settings,
                     &sync_state,
@@ -880,6 +899,8 @@ hint: If you are running a script with `{}` in the shebang, you may need to incl
                     lock.as_ref()
                         .map(|(lock, install_path)| (lock, install_path.as_ref())),
                 ),
+                // TODO(bluefact): Respect build constraints for `uv run --with` dependencies.
+                Constraints::default(),
                 &base_interpreter,
                 &settings,
                 &network_settings,

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

@@ -11,12 +11,12 @@ use uv_auth::UrlAuthPolicies;
 use uv_cache::Cache;
 use uv_client::{FlatIndexClient, RegistryClientBuilder};
 use uv_configuration::{
-    Concurrency, DependencyGroups, DependencyGroupsWithDefaults, DryRun, EditableMode,
+    Concurrency, Constraints, DependencyGroups, DependencyGroupsWithDefaults, DryRun, EditableMode,
     ExtrasSpecification, HashCheckingMode, InstallOptions, PreviewMode,
 };
 use uv_dispatch::BuildDispatch;
 use uv_distribution_types::{
-    DirectorySourceDist, Dist, Index, Resolution, ResolvedDist, SourceDist,
+    DirectorySourceDist, Dist, Index, Requirement, Resolution, ResolvedDist, SourceDist,
 };
 use uv_fs::Simplified;
 use uv_installer::SitePackages;
@@ -274,12 +274,33 @@ pub(crate) async fn sync(
                 ));
             }
 
+            // Parse the requirements from the script.
             let spec = script_specification(Pep723ItemRef::Script(script), &settings.resolver)?
                 .unwrap_or_default();
+
+            // Parse the build constraints from the script.
+            let build_constraints = script
+                .metadata
+                .tool
+                .as_ref()
+                .and_then(|tool| {
+                    tool.uv
+                        .as_ref()
+                        .and_then(|uv| uv.build_constraint_dependencies.as_ref())
+                })
+                .map(|constraints| {
+                    Constraints::from_requirements(
+                        constraints
+                            .iter()
+                            .map(|constraint| Requirement::from(constraint.clone())),
+                    )
+                });
+
             match update_environment(
                 Deref::deref(&environment).clone(),
                 spec,
                 modifications,
+                build_constraints.unwrap_or_default(),
                 &settings,
                 &network_settings,
                 &PlatformState::default(),

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

@@ -168,6 +168,7 @@ pub(crate) fn install_executables(
     requirements: Vec<Requirement>,
     constraints: Vec<Requirement>,
     overrides: Vec<Requirement>,
+    build_constraints: Vec<Requirement>,
     printer: Printer,
 ) -> anyhow::Result<ExitStatus> {
     let site_packages = SitePackages::from_environment(environment)?;
@@ -289,6 +290,7 @@ pub(crate) fn install_executables(
         requirements,
         constraints,
         overrides,
+        build_constraints,
         python,
         target_entry_points
             .into_iter()