Support default-extras config in the project interface.

crates/uv-cli/src/lib.rs

@@ -2903,12 +2903,28 @@ pub struct RunArgs {
     #[arg(long, conflicts_with = "extra")]
     pub all_extras: bool,
 
-    /// Exclude the specified optional dependencies, if `--all-extras` is supplied.
+    /// Disable the specified extra.
+    ///
+    /// This options always takes precedence over default extras,
+    /// `--all-extras`, and `--extra`.
     ///
     /// May be provided multiple times.
     #[arg(long)]
     pub no_extra: Vec<ExtraName>,
 
+    /// Ignore the default extras.
+    ///
+    /// uv includes the extras defined in `tool.uv.default-extras` by default.
+    /// This disables that option, however, specific extras can still be included with `--extra`.
+    #[arg(long)]
+    pub no_default_extras: bool,
+
+    /// Only include dependencies from the specified extra.
+    ///
+    /// May be provided multiple times. Implies `--no-default-extras`.
+    #[arg(long, conflicts_with_all = ["extra", "all_extras"])]
+    pub only_extra: Vec<ExtraName>,
+
     #[arg(long, overrides_with("all_extras"), hide = true)]
     pub no_all_extras: bool,
 
@@ -3194,12 +3210,28 @@ pub struct SyncArgs {
     #[arg(long, conflicts_with = "extra")]
     pub all_extras: bool,
 
-    /// Exclude the specified optional dependencies, if `--all-extras` is supplied.
+    /// Disable the specified extra.
+    ///
+    /// This options always takes precedence over default extras,
+    /// `--all-extras`, and `--extra`.
     ///
     /// May be provided multiple times.
     #[arg(long)]
     pub no_extra: Vec<ExtraName>,
 
+    /// Ignore the default extras.
+    ///
+    /// uv includes the extras defined in `tool.uv.default-extras` by default.
+    /// This disables that option, however, specific extras can still be included with `--extra`.
+    #[arg(long)]
+    pub no_default_extras: bool,
+
+    /// Only include dependencies from the specified extra.
+    ///
+    /// May be provided multiple times. Implies `--no-default-extras`.
+    #[arg(long, conflicts_with_all = ["extra", "all_extras"])]
+    pub only_extra: Vec<ExtraName>,
+
     #[arg(long, overrides_with("all_extras"), hide = true)]
     pub no_all_extras: bool,
 
@@ -3933,12 +3965,28 @@ pub struct ExportArgs {
     #[arg(long, conflicts_with = "extra")]
     pub all_extras: bool,
 
-    /// Exclude the specified optional dependencies, if `--all-extras` is supplied.
+    /// Disable the specified extra.
+    ///
+    /// This options always takes precedence over default extras,
+    /// `--all-extras`, and `--extra`.
     ///
     /// May be provided multiple times.
     #[arg(long)]
     pub no_extra: Vec<ExtraName>,
 
+    /// Ignore the default extras.
+    ///
+    /// uv includes the extras defined in `tool.uv.default-extras` by default.
+    /// This disables that option, however, specific extras can still be included with `--extra`.
+    #[arg(long)]
+    pub no_default_extras: bool,
+
+    /// Only include dependencies from the specified extra.
+    ///
+    /// May be provided multiple times. Implies `--no-default-extras`.
+    #[arg(long, conflicts_with_all = ["extra", "all_extras"])]
+    pub only_extra: Vec<ExtraName>,
+
     #[arg(long, overrides_with("all_extras"), hide = true)]
     pub no_all_extras: bool,
 

crates/uv-settings/src/lib.rs

@@ -216,6 +216,12 @@ fn validate_uv_toml(path: &Path, options: &Options) -> Result<(), Error> {
             "default-groups",
         ));
     }
+    if options.default_extras.is_some() {
+        return Err(Error::PyprojectOnlyField(
+            path.to_path_buf(),
+            "default-extras",
+        ));
+    }
     if options.managed.is_some() {
         return Err(Error::PyprojectOnlyField(path.to_path_buf(), "managed"));
     }

crates/uv-settings/src/settings.rs

@@ -140,6 +140,9 @@ pub struct Options {
     #[cfg_attr(feature = "schemars", schemars(skip))]
     pub default_groups: Option<serde::de::IgnoredAny>,
 
+    #[cfg_attr(feature = "schemars", schemars(skip))]
+    pub default_extras: Option<serde::de::IgnoredAny>,
+
     #[cfg_attr(feature = "schemars", schemars(skip))]
     pub managed: Option<serde::de::IgnoredAny>,
 
@@ -1870,6 +1873,7 @@ pub struct OptionsWire {
     managed: Option<serde::de::IgnoredAny>,
     r#package: Option<serde::de::IgnoredAny>,
     default_groups: Option<serde::de::IgnoredAny>,
+    default_extras: Option<serde::de::IgnoredAny>,
     dev_dependencies: Option<serde::de::IgnoredAny>,
 
     // Build backend
@@ -1934,6 +1938,7 @@ impl From<OptionsWire> for Options {
             workspace,
             sources,
             default_groups,
+            default_extras,
             dev_dependencies,
             managed,
             package,
@@ -2010,6 +2015,7 @@ impl From<OptionsWire> for Options {
             sources,
             dev_dependencies,
             default_groups,
+            default_extras,
             managed,
             package,
         }

crates/uv-workspace/src/pyproject.rs

@@ -22,7 +22,7 @@ use uv_distribution_types::{Index, IndexName, RequirementSource};
 use uv_fs::{PortablePathBuf, relative_to};
 use uv_git_types::GitReference;
 use uv_macros::OptionsMetadata;
-use uv_normalize::{DefaultGroups, ExtraName, GroupName, PackageName};
+use uv_normalize::{DefaultExtras, DefaultGroups, ExtraName, GroupName, PackageName};
 use uv_pep440::{Version, VersionSpecifiers};
 use uv_pep508::MarkerTree;
 use uv_pypi_types::{
@@ -341,6 +341,18 @@ pub struct ToolUv {
     )]
     pub package: Option<bool>,
 
+    /// The list of `optional-dependencies` extras to install by default.
+    ///
+    /// Can also be the literal "all" to default enable all extras.
+    #[option(
+        default = r#"[""]"#,
+        value_type = r#"str | list[str]"#,
+        example = r#"
+            default-extras = ["docs", "dev"]
+        "#
+    )]
+    pub default_extras: Option<DefaultExtras>,
+
     /// The list of `dependency-groups` to install by default.
     ///
     /// Can also be the literal `"all"` to default enable all groups.

crates/uv-workspace/src/workspace.rs

@@ -1817,6 +1817,7 @@ mod tests {
                       },
                       "managed": null,
                       "package": null,
+                      "default-extras": null,
                       "default-groups": null,
                       "dev-dependencies": null,
                       "override-dependencies": null,
@@ -1912,6 +1913,7 @@ mod tests {
                       },
                       "managed": null,
                       "package": null,
+                      "default-extras": null,
                       "default-groups": null,
                       "dev-dependencies": null,
                       "override-dependencies": null,
@@ -2122,6 +2124,7 @@ mod tests {
                       },
                       "managed": null,
                       "package": null,
+                      "default-extras": null,
                       "default-groups": null,
                       "dev-dependencies": null,
                       "override-dependencies": null,
@@ -2229,6 +2232,7 @@ mod tests {
                       },
                       "managed": null,
                       "package": null,
+                      "default-extras": null,
                       "default-groups": null,
                       "dev-dependencies": null,
                       "override-dependencies": null,
@@ -2349,6 +2353,7 @@ mod tests {
                       },
                       "managed": null,
                       "package": null,
+                      "default-extras": null,
                       "default-groups": null,
                       "dev-dependencies": null,
                       "override-dependencies": null,
@@ -2443,6 +2448,7 @@ mod tests {
                       },
                       "managed": null,
                       "package": null,
+                      "default-extras": null,
                       "default-groups": null,
                       "dev-dependencies": null,
                       "override-dependencies": null,

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

@@ -29,7 +29,7 @@ use uv_distribution_types::{
 use uv_fs::{LockedFile, Simplified};
 use uv_git::GIT_STORE;
 use uv_git_types::GitReference;
-use uv_normalize::{DEV_DEPENDENCIES, DefaultExtras, PackageName};
+use uv_normalize::{DEV_DEPENDENCIES, PackageName};
 use uv_pep508::{ExtraName, MarkerTree, UnnamedRequirement, VersionOrUrl};
 use uv_pypi_types::{ParsedUrl, VerbatimParsedUrl};
 use uv_python::{Interpreter, PythonDownloads, PythonEnvironment, PythonPreference, PythonRequest};
@@ -53,7 +53,7 @@ use crate::commands::project::lock::LockMode;
 use crate::commands::project::lock_target::LockTarget;
 use crate::commands::project::{
     PlatformState, ProjectEnvironment, ProjectError, ProjectInterpreter, ScriptInterpreter,
-    UniversalState, default_dependency_groups, init_script_python_requirement,
+    UniversalState, default_dependency_groups, default_extras, init_script_python_requirement,
 };
 use crate::commands::reporters::{PythonDownloadReporter, ResolverReporter};
 use crate::commands::{ExitStatus, ScriptPath, diagnostics, project};
@@ -970,7 +970,7 @@ async fn lock_and_sync(
     let default_groups = default_dependency_groups(project.pyproject_toml())?;
 
     // Determine the default extras to include.
-    let default_extras = DefaultExtras::default();
+    let default_extras = default_extras(project.pyproject_toml())?;
 
     // Identify the installation target.
     let target = match &project {

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

@@ -25,7 +25,7 @@ use crate::commands::project::lock::{LockMode, LockOperation};
 use crate::commands::project::lock_target::LockTarget;
 use crate::commands::project::{
     ProjectError, ProjectInterpreter, ScriptInterpreter, UniversalState, default_dependency_groups,
-    detect_conflicts,
+    default_extras, detect_conflicts,
 };
 use crate::commands::{ExitStatus, OutputWriter, diagnostics};
 use crate::printer::Printer;
@@ -118,10 +118,9 @@ pub(crate) async fn export(
 
     // Determine the default extras to include.
     let default_extras = match &target {
-        ExportTarget::Project(_project) => DefaultExtras::default(),
+        ExportTarget::Project(project) => default_extras(project.pyproject_toml())?,
         ExportTarget::Script(_) => DefaultExtras::default(),
     };
-
     let dev = dev.with_defaults(default_groups);
     let extras = extras.with_defaults(default_extras);
 

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

@@ -13,7 +13,7 @@ use uv_cache_key::cache_digest;
 use uv_client::{BaseClientBuilder, FlatIndexClient, RegistryClientBuilder};
 use uv_configuration::{
     Concurrency, Constraints, DependencyGroupsWithDefaults, DryRun, ExtrasSpecification,
-    PreviewMode, Reinstall, SourceStrategy, Upgrade,
+    ExtrasSpecificationWithDefaults, PreviewMode, Reinstall, SourceStrategy, Upgrade,
 };
 use uv_dispatch::{BuildDispatch, SharedState};
 use uv_distribution::{DistributionDatabase, LoweredRequirement};
@@ -23,7 +23,9 @@ use uv_distribution_types::{
 use uv_fs::{CWD, LockedFile, Simplified};
 use uv_git::ResolvedRepositoryReference;
 use uv_installer::{SatisfiesResult, SitePackages};
-use uv_normalize::{DEV_DEPENDENCIES, DefaultGroups, ExtraName, GroupName, PackageName};
+use uv_normalize::{
+    DEV_DEPENDENCIES, DefaultExtras, DefaultGroups, ExtraName, GroupName, PackageName,
+};
 use uv_pep440::{Version, VersionSpecifiers};
 use uv_pep508::MarkerTreeContents;
 use uv_pypi_types::{ConflictPackage, ConflictSet, Conflicts};
@@ -174,6 +176,11 @@ pub(crate) enum ProjectError {
     #[error("PEP 723 scripts do not support dependency groups, but group `{0}` was specified")]
     MissingGroupScript(GroupName),
 
+    #[error(
+        "Default extra `{0}` (from `tool.uv.default-extras`) is not defined in the project's `optional-dependencies` table"
+    )]
+    MissingDefaultExtra(ExtraName),
+
     #[error(
         "Default group `{0}` (from `tool.uv.default-groups`) is not defined in the project's `dependency-groups` table"
     )]
@@ -2428,12 +2435,40 @@ pub(crate) fn default_dependency_groups(
     }
 }
 
+/// Returns the default extras from the [`PyProjectToml`].
+#[allow(clippy::result_large_err)]
+pub(crate) fn default_extras(
+    pyproject_toml: &PyProjectToml,
+) -> Result<DefaultExtras, ProjectError> {
+    if let Some(defaults) = pyproject_toml
+        .tool
+        .as_ref()
+        .and_then(|tool| tool.uv.as_ref().and_then(|uv| uv.default_extras.as_ref()))
+    {
+        if let DefaultExtras::List(defaults) = defaults {
+            for extra in defaults {
+                if pyproject_toml
+                    .project
+                    .as_ref()
+                    .and_then(|project| project.optional_dependencies.as_ref())
+                    .is_none_or(|extras| !extras.contains_key(extra))
+                {
+                    return Err(ProjectError::MissingDefaultExtra(extra.clone()));
+                }
+            }
+        }
+        Ok(defaults.clone())
+    } else {
+        Ok(DefaultExtras::default())
+    }
+}
+
 /// Validate that we aren't trying to install extras or groups that
 /// are declared as conflicting.
 #[allow(clippy::result_large_err)]
 pub(crate) fn detect_conflicts(
     lock: &Lock,
-    extras: &ExtrasSpecification,
+    extras: &ExtrasSpecificationWithDefaults,
     dev: &DependencyGroupsWithDefaults,
 ) -> Result<(), ProjectError> {
     // Note that we need to collect all extras and groups that match in

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

@@ -13,7 +13,7 @@ use uv_configuration::{
     PreviewMode,
 };
 use uv_fs::Simplified;
-use uv_normalize::{DEV_DEPENDENCIES, DefaultExtras};
+use uv_normalize::DEV_DEPENDENCIES;
 use uv_pep508::PackageName;
 use uv_python::{PythonDownloads, PythonPreference, PythonRequest};
 use uv_scripts::{Pep723ItemRef, Pep723Metadata, Pep723Script};
@@ -31,7 +31,7 @@ use crate::commands::project::lock::LockMode;
 use crate::commands::project::lock_target::LockTarget;
 use crate::commands::project::{
     ProjectEnvironment, ProjectError, ProjectInterpreter, ScriptInterpreter, UniversalState,
-    default_dependency_groups,
+    default_dependency_groups, default_extras,
 };
 use crate::commands::{ExitStatus, diagnostics, project};
 use crate::printer::Printer;
@@ -318,7 +318,7 @@ pub(crate) async fn remove(
     let default_groups = default_dependency_groups(project.pyproject_toml())?;
 
     // Determine the default extras to include.
-    let default_extras = DefaultExtras::default();
+    let default_extras = default_extras(project.pyproject_toml())?;
 
     // Identify the installation target.
     let target = match &project {

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

@@ -51,7 +51,7 @@ use crate::commands::project::lock_target::LockTarget;
 use crate::commands::project::{
     EnvironmentSpecification, PreferenceSource, ProjectEnvironment, ProjectError,
     ScriptEnvironment, ScriptInterpreter, UniversalState, WorkspacePython,
-    default_dependency_groups, script_specification, update_environment,
+    default_dependency_groups, default_extras, script_specification, update_environment,
     validate_project_requires_python,
 };
 use crate::commands::reporters::PythonDownloadReporter;
@@ -683,7 +683,7 @@ hint: If you are running a script with `{}` in the shebang, you may need to incl
                 let default_groups = default_dependency_groups(project.pyproject_toml())?;
 
                 // Determine the default extras to include.
-                let default_extras = DefaultExtras::default();
+                let default_extras = default_extras(project.pyproject_toml())?;
 
                 // Determine the lock mode.
                 let mode = if frozen {

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

@@ -40,7 +40,8 @@ use crate::commands::project::lock::{LockMode, LockOperation, LockResult};
 use crate::commands::project::lock_target::LockTarget;
 use crate::commands::project::{
     PlatformState, ProjectEnvironment, ProjectError, ScriptEnvironment, UniversalState,
-    default_dependency_groups, detect_conflicts, script_specification, update_environment,
+    default_dependency_groups, default_extras, detect_conflicts, script_specification,
+    update_environment,
 };
 use crate::commands::{ExitStatus, diagnostics};
 use crate::printer::Printer;
@@ -124,7 +125,7 @@ pub(crate) async fn sync(
 
     // Determine the default extras to include.
     let default_extras = match &target {
-        SyncTarget::Project(_project) => DefaultExtras::default(),
+        SyncTarget::Project(project) => default_extras(project.pyproject_toml())?,
         SyncTarget::Script(..) => DefaultExtras::default(),
     };