Add support for virtual projects (#6585)

## Summary

The basic idea here is: any project can either be a package, or not
("virtual").

If a project is virtual, we don't build or install it.

A project is virtual if either of the following are true:

- `tool.uv.virtual = true` is set.
- `[build-system]` is absent.

The concept of "virtual projects" only applies to workspace member right
now; it doesn't apply to `path` dependencies which are treated like
arbitrary Python source trees.

TODOs that should be resolved prior to merging:

- [ ] Documentation
- [ ] How do we reconcile this with "virtual workspace roots" which are
a little different -- they omit `[project]` entirely and don't even have
a name?
- [x] `uv init --virtual` should create a virtual project rather than a
virtual workspace.
- [x] Running `uv sync` in a virtual project after `uv init --virtual`
shows `Audited 0 packages in 0.01ms`, which is awkward. (See:
#6588.)

Closes #6511.

crates/uv-cli/src/lib.rs

@@ -2099,11 +2099,12 @@ pub struct InitArgs {
  #[arg(long)]
  pub name: Option<PackageName>,
 
- /// Create a virtual workspace instead of a project.
+ /// Create a virtual project, rather than a package.
  ///
- /// A virtual workspace does not define project dependencies and cannot be
- /// published. Instead, workspace members declare project dependencies.
- /// Development dependencies may still be declared.
+ /// A virtual project is a project that is not intended to be built as a Python package,
+ /// such as a project that only contains scripts or other application code.
+ ///
+ /// Virtual projects themselves are not installed into the Python environment.
  #[arg(long)]
  pub r#virtual: bool,
 

crates/uv-settings/src/settings.rs

@@ -70,6 +70,10 @@ pub struct Options {
  #[serde(default, skip_serializing)]
  #[cfg_attr(feature = "schemars", schemars(skip))]
  managed: serde::de::IgnoredAny,
+
+ #[serde(default, skip_serializing)]
+ #[cfg_attr(feature = "schemars", schemars(skip))]
+ r#package: serde::de::IgnoredAny,
 }
 
 impl Options {

crates/uv-workspace/src/pyproject.rs

@@ -33,6 +33,10 @@ pub struct PyProjectToml {
  /// The raw unserialized document.
  #[serde(skip)]
  pub raw: String,
+
+ /// Used to determine whether a `build-system` is present.
+ #[serde(default, skip_serializing)]
+ build_system: Option<serde::de::IgnoredAny>,
 }
 
 impl PyProjectToml {
@@ -41,6 +45,23 @@ impl PyProjectToml {
  let pyproject = toml::from_str(&raw)?;
  Ok(PyProjectToml { raw, ..pyproject })
  }
+
+ /// Returns `true` if the project should be considered a Python package, as opposed to a
+ /// non-package ("virtual") project.
+ pub fn is_package(&self) -> bool {
+ // If `tool.uv.package` is set, defer to that explicit setting.
+ if let Some(is_package) = self
+ .tool
+ .as_ref()
+ .and_then(|tool| tool.uv.as_ref())
+ .and_then(|uv| uv.package)
+ {
+ return is_package;
+ }
+
+ // Otherwise, a project is assumed to be a package if `build-system` is present.
+ self.build_system.is_some()
+ }
 }
 
 // Ignore raw document in comparison.
@@ -100,6 +121,24 @@ pub struct ToolUv {
  "#
  )]
  pub managed: Option<bool>,
+ /// Whether the project should be considered a Python package, or a non-package ("virtual")
+ /// project.
+ ///
+ /// Packages are built and installed into the virtual environment in editable mode and thus
+ /// require a build backend, while virtual projects are _not_ built or installed; instead, only
+ /// their dependencies are included in the virtual environment.
+ ///
+ /// Creating a package requires that a `build-system` is present in the `pyproject.toml`, and
+ /// that the project adheres to a structure that adheres to the build backend's expectations
+ /// (e.g., a `src` layout).
+ #[option(
+ default = r#"true"#,
+ value_type = "bool",
+ example = r#"
+ package = false
+ "#
+ )]
+ pub package: Option<bool>,
  /// The project's development dependencies. Development dependencies will be installed by
  /// default in `uv run` and `uv sync`, but will not appear in the project's published metadata.
  #[cfg_attr(

crates/uv-workspace/src/workspace.rs

@@ -1339,15 +1339,15 @@ impl VirtualProject {
  }
  }
 
- /// Return the [`PackageName`] of the project, if it's not a virtual workspace.
+ /// Return the [`PackageName`] of the project, if it's not a virtual workspace root.
  pub fn project_name(&self) -> Option<&PackageName> {
  match self {
  VirtualProject::Project(project) => Some(project.project_name()),
  VirtualProject::Virtual(_) => None,
  }
  }
 
- /// Returns `true` if the project is a virtual workspace.
+ /// Returns `true` if the project is a virtual workspace root.
  pub fn is_virtual(&self) -> bool {
  matches!(self, VirtualProject::Virtual(_))
  }
@@ -1535,6 +1535,7 @@ mod tests {
  "exclude": null
  },
  "managed": null,
+ "package": null,
  "dev-dependencies": null,
  "environments": null,
  "override-dependencies": null,
@@ -1607,6 +1608,7 @@ mod tests {
  "exclude": null
  },
  "managed": null,
+ "package": null,
  "dev-dependencies": null,
  "environments": null,
  "override-dependencies": null,

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

@@ -15,7 +15,7 @@ use uv_python::{
 };
 use uv_resolver::RequiresPython;
 use uv_workspace::pyproject_mut::{DependencyTarget, PyProjectTomlMut};
-use uv_workspace::{check_nested_workspaces, DiscoveryOptions, Workspace, WorkspaceError};
+use uv_workspace::{DiscoveryOptions, Workspace, WorkspaceError};
 
 use crate::commands::project::find_requires_python;
 use crate::commands::reporters::PythonDownloadReporter;
@@ -69,24 +69,21 @@ pub(crate) async fn init(
  }
  };
 
- if r#virtual {
- init_virtual_workspace(&path, no_workspace)?;
- } else {
- init_project(
- &path,
- &name,
- no_readme,
- python,
- no_workspace,
- python_preference,
- python_downloads,
- connectivity,
- native_tls,
- cache,
- printer,
- )
- .await?;
- }
+ init_project(
+ &path,
+ &name,
+ r#virtual,
+ no_readme,
+ python,
+ no_workspace,
+ python_preference,
+ python_downloads,
+ connectivity,
+ native_tls,
+ cache,
+ printer,
+ )
+ .await?;
 
  // Create the `README.md` if it does not already exist.
  if !no_readme {
@@ -126,29 +123,12 @@ pub(crate) async fn init(
  Ok(ExitStatus::Success)
 }
 
-/// Initialize a virtual workspace at the given path.
-fn init_virtual_workspace(path: &Path, no_workspace: bool) -> Result<()> {
- // Ensure that we aren't creating a nested workspace.
- if !no_workspace {
- check_nested_workspaces(path, &DiscoveryOptions::default());
- }
-
- // Create the `pyproject.toml`.
- let pyproject = indoc::indoc! {r"
- [tool.uv.workspace]
- members = []
- "};
-
- fs_err::create_dir_all(path)?;
- fs_err::write(path.join("pyproject.toml"), pyproject)?;
-
- Ok(())
-}
-
 /// Initialize a project (and, implicitly, a workspace root) at the given path.
+#[allow(clippy::fn_params_excessive_bools)]
 async fn init_project(
  path: &Path,
  name: &PackageName,
+ r#virtual: bool,
  no_readme: bool,
  python: Option<String>,
  no_workspace: bool,
@@ -265,38 +245,56 @@ async fn init_project(
  RequiresPython::greater_than_equal_version(&interpreter.python_minor_version())
  };
 
- // Create the `pyproject.toml`.
- let pyproject = indoc::formatdoc! {r#"
- [project]
- name = "{name}"
- version = "0.1.0"
- description = "Add your description here"{readme}
- requires-python = "{requires_python}"
- dependencies = []
+ if r#virtual {
+ // Create the `pyproject.toml`, but omit `[build-system]`.
+ let pyproject = indoc::formatdoc! {r#"
+ [project]
+ name = "{name}"
+ version = "0.1.0"
+ description = "Add your description here"{readme}
+ requires-python = "{requires_python}"
+ dependencies = []
+ "#,
+ readme = if no_readme { "" } else { "\nreadme = \"README.md\"" },
+ requires_python = requires_python.specifiers(),
+ };
 
- [build-system]
- requires = ["hatchling"]
- build-backend = "hatchling.build"
- "#,
- readme = if no_readme { "" } else { "\nreadme = \"README.md\"" },
- requires_python = requires_python.specifiers(),
- };
+ fs_err::create_dir_all(path)?;
+ fs_err::write(path.join("pyproject.toml"), pyproject)?;
+ } else {
+ // Create the `pyproject.toml`.
+ let pyproject = indoc::formatdoc! {r#"
+ [project]
+ name = "{name}"
+ version = "0.1.0"
+ description = "Add your description here"{readme}
+ requires-python = "{requires_python}"
+ dependencies = []
+
+ [build-system]
+ requires = ["hatchling"]
+ build-backend = "hatchling.build"
+ "#,
+ readme = if no_readme { "" } else { "\nreadme = \"README.md\"" },
+ requires_python = requires_python.specifiers(),
+ };
 
- fs_err::create_dir_all(path)?;
- fs_err::write(path.join("pyproject.toml"), pyproject)?;
+  fs_err::create_dir_all(path)?;
+  fs_err::write(path.join("pyproject.toml"), pyproject)?;
 
- // Create `src/{name}/__init__.py`, if it doesn't exist already.
- let src_dir = path.join("src").join(&*name.as_dist_info_name());
- let init_py = src_dir.join("__init__.py");
- if !init_py.try_exists()? {
- fs_err::create_dir_all(&src_dir)?;
- fs_err::write(
- init_py,
- indoc::formatdoc! {r#"
+  // Create `src/{name}/__init__.py`, if it doesn't exist already.
+  let src_dir = path.join("src").join(&*name.as_dist_info_name());
+  let init_py = src_dir.join("__init__.py");
+  if !init_py.try_exists()? {
+  fs_err::create_dir_all(&src_dir)?;
+  fs_err::write(
+  init_py,
+  indoc::formatdoc! {r#"
  def hello() -> str:
  return "Hello from {name}!"
  "#},
- )?;
+ )?;
+ }
  }
 
  if let Some(workspace) = workspace {

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

@@ -1,5 +1,8 @@
 use anyhow::{Context, Result};
 use itertools::Itertools;
+use rustc_hash::FxHashSet;
+
+use distribution_types::Name;
 use pep508_rs::MarkerTree;
 use uv_auth::store_credentials_from_url;
 use uv_cache::Cache;
@@ -195,6 +198,9 @@ pub(super) async fn do_sync(
  // Read the lockfile.
  let resolution = lock.to_resolution(project, &markers, tags, extras, &dev)?;
 
+ // Always skip virtual projects, which shouldn't be built or installed.
+ let resolution = apply_no_virtual_project(resolution, project);
+
  // Filter resolution based on install-specific options.
  let resolution = install_options.filter_resolution(resolution, project);
 
@@ -289,3 +295,32 @@ pub(super) async fn do_sync(
 
  Ok(())
 }
+
+/// Filter out any virtual workspace members.
+fn apply_no_virtual_project(
+ resolution: distribution_types::Resolution,
+ project: &VirtualProject,
+) -> distribution_types::Resolution {
+ let VirtualProject::Project(project) = project else {
+ // If the project is _only_ a virtual workspace root, we don't need to filter it out.
+ return resolution;
+ };
+
+ let virtual_members = project
+ .workspace()
+ .packages()
+ .iter()
+ .filter_map(|(name, package)| {
+ // A project is a package if it's explicitly marked as such, _or_ if a build system is
+ // present.
+ if package.pyproject_toml().is_package() {
+ None
+ } else {
+ Some(name)
+ }
+ })
+ .collect::<FxHashSet<_>>();
+
+ // Remove any virtual members from the resolution.
+ resolution.filter(|dist| !virtual_members.contains(dist.name()))
+}

crates/uv/tests/common/mod.rs

@@ -1110,8 +1110,9 @@ pub fn make_project(dir: &Path, name: &str, body: &str) -> anyhow::Result<()> {
  {body}
 
  [build-system]
- requires = ["flit_core>=3.8,<4"]
- build-backend = "flit_core.buildapi"
+ requires = ["setuptools>=42", "wheel"]
+ build-backend = "setuptools.build_meta"
+
  "#
  };
  fs_err::create_dir_all(dir)?;