Add uv sync --dry-run

Author: charliermarsh

crates/uv-cli/src/lib.rs

@@ -3091,6 +3091,13 @@ pub struct SyncArgs {
     #[arg(long, env = EnvVars::UV_FROZEN, value_parser = clap::builder::BoolishValueParser::new(), conflicts_with = "locked")]
     pub frozen: bool,
 
+    /// Perform a dry run, without writing the lockfile or modifying the project environment.
+    ///
+    /// In dry-run mode, uv will resolve the project's dependencies and report on the resulting
+    /// changes to both the lockfile and the project environment, but will not modify either.
+    #[arg(long, conflicts_with = "locked", conflicts_with = "frozen")]
+    pub dry_run: bool,
+
     #[command(flatten)]
     pub installer: ResolverInstallerArgs,
 

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

@@ -46,8 +46,8 @@ use crate::commands::project::install_target::InstallTarget;
 use crate::commands::project::lock::LockMode;
 use crate::commands::project::lock_target::LockTarget;
 use crate::commands::project::{
-    init_script_python_requirement, PlatformState, ProjectError, ProjectInterpreter,
-    ScriptInterpreter, UniversalState,
+    init_script_python_requirement, PlatformState, ProjectEnvironment, ProjectError,
+    ProjectInterpreter, ScriptInterpreter, UniversalState,
 };
 use crate::commands::reporters::{PythonDownloadReporter, ResolverReporter};
 use crate::commands::{diagnostics, project, ExitStatus};
@@ -223,7 +223,7 @@ pub(crate) async fn add(
             AddTarget::Project(project, Box::new(PythonTarget::Interpreter(interpreter)))
         } else {
             // Discover or create the virtual environment.
-            let venv = project::get_or_init_environment(
+            let venv = ProjectEnvironment::get_or_init(
                 project.workspace(),
                 python.as_deref().map(PythonRequest::parse),
                 &install_mirrors,
@@ -235,9 +235,11 @@ pub(crate) async fn add(
                 no_config,
                 active,
                 cache,
+                false,
                 printer,
             )
-            .await?;
+            .await?
+            .into_environment();
 
             AddTarget::Project(project, Box::new(PythonTarget::Environment(venv)))
         }
@@ -880,6 +882,7 @@ async fn lock_and_sync(
         native_tls,
         allow_insecure_host,
         cache,
+        false,
         printer,
         preview,
     )

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

@@ -222,7 +222,6 @@ pub(super) async fn do_safe_lock(
     mode: LockMode<'_>,
     target: LockTarget<'_>,
     settings: ResolverSettingsRef<'_>,
-
     state: &UniversalState,
     logger: Box<dyn ResolveLogger>,
     connectivity: Connectivity,
@@ -1122,10 +1121,11 @@ fn report_upgrades(
                 .unwrap_or_else(|| "(dynamic)".to_string())
         }
 
-        updated = true;
         match (existing_packages.get(name), new_distributions.get(name)) {
             (Some(existing_versions), Some(new_versions)) => {
                 if existing_versions != new_versions {
+                    updated = true;
+
                     let existing_versions = existing_versions
                         .iter()
                         .map(|version| format_version(*version))
@@ -1144,6 +1144,8 @@ fn report_upgrades(
                 }
             }
             (Some(existing_versions), None) => {
+                updated = true;
+
                 let existing_versions = existing_versions
                     .iter()
                     .map(|version| format_version(*version))
@@ -1156,6 +1158,8 @@ fn report_upgrades(
                 )?;
             }
             (None, Some(new_versions)) => {
+                updated = true;
+
                 let new_versions = new_versions
                     .iter()
                     .map(|version| format_version(*version))

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

@@ -930,124 +930,170 @@ impl ScriptPython {
     }
 }
 
-/// Initialize a virtual environment for the current project.
-pub(crate) async fn get_or_init_environment(
-    workspace: &Workspace,
-    python: Option<PythonRequest>,
-    install_mirrors: &PythonInstallMirrors,
-    python_preference: PythonPreference,
-    python_downloads: PythonDownloads,
-    connectivity: Connectivity,
-    native_tls: bool,
-    allow_insecure_host: &[TrustedHost],
-    no_config: bool,
-    active: Option<bool>,
-    cache: &Cache,
-    printer: Printer,
-) -> Result<PythonEnvironment, ProjectError> {
-    // Lock the project environment to avoid synchronization issues.
-    let _lock = ProjectInterpreter::lock(workspace).await?;
+/// The Python environment for a project.
+#[derive(Debug)]
+enum ProjectEnvironment {
+    /// An existing [`PythonEnvironment`] was discovered, which satisfies the project's requirements.
+    Existing(PythonEnvironment),
+    /// An existing [`PythonEnvironment`] was discovered, but did not satisfy the project's
+    /// requirements, and so was replaced.
+    ///
+    /// In `--dry-run` mode, the environment will not be replaced, but this variant will still be
+    /// returned.
+    Replaced(PythonEnvironment, PathBuf),
+    /// A new [`PythonEnvironment`] was created.
+    ///
+    /// In `--dry-run` mode, the environment will not be created, but this variant will still be
+    /// returned.
+    New(PythonEnvironment, PathBuf),
+}
 
-    match ProjectInterpreter::discover(
-        workspace,
-        workspace.install_path().as_ref(),
-        python,
-        python_preference,
-        python_downloads,
-        connectivity,
-        native_tls,
-        allow_insecure_host,
-        install_mirrors,
-        no_config,
-        active,
-        cache,
-        printer,
-    )
-    .await?
-    {
-        // If we found an existing, compatible environment, use it.
-        ProjectInterpreter::Environment(environment) => Ok(environment),
-
-        // Otherwise, create a virtual environment with the discovered interpreter.
-        ProjectInterpreter::Interpreter(interpreter) => {
-            let venv = workspace.venv(active);
-
-            // Avoid removing things that are not virtual environments
-            let should_remove = match (venv.try_exists(), venv.join("pyvenv.cfg").try_exists()) {
-                // It's a virtual environment we can remove it
-                (_, Ok(true)) => true,
-                // It doesn't exist at all, we should use it without deleting it to avoid TOCTOU bugs
-                (Ok(false), Ok(false)) => false,
-                // If it's not a virtual environment, bail
-                (Ok(true), Ok(false)) => {
-                    // Unless it's empty, in which case we just ignore it
-                    if venv.read_dir().is_ok_and(|mut dir| dir.next().is_none()) {
-                        false
-                    } else {
+impl ProjectEnvironment {
+    /// Initialize a virtual environment for the current project.
+    pub(crate) async fn get_or_init(
+        workspace: &Workspace,
+        python: Option<PythonRequest>,
+        install_mirrors: &PythonInstallMirrors,
+        python_preference: PythonPreference,
+        python_downloads: PythonDownloads,
+        connectivity: Connectivity,
+        native_tls: bool,
+        allow_insecure_host: &[TrustedHost],
+        no_config: bool,
+        active: Option<bool>,
+        cache: &Cache,
+        dry_run: bool,
+        printer: Printer,
+    ) -> Result<Self, ProjectError> {
+        // Lock the project environment to avoid synchronization issues.
+        let _lock = ProjectInterpreter::lock(workspace).await?;
+
+        match ProjectInterpreter::discover(
+            workspace,
+            workspace.install_path().as_ref(),
+            python,
+            python_preference,
+            python_downloads,
+            connectivity,
+            native_tls,
+            allow_insecure_host,
+            install_mirrors,
+            no_config,
+            active,
+            cache,
+            printer,
+        )
+        .await?
+        {
+            // If we found an existing, compatible environment, use it.
+            ProjectInterpreter::Environment(environment) => Ok(Self::Existing(environment)),
+
+            // Otherwise, create a virtual environment with the discovered interpreter.
+            ProjectInterpreter::Interpreter(interpreter) => {
+                let venv = workspace.venv(active);
+
+                // Avoid removing things that are not virtual environments
+                let replace = match (venv.try_exists(), venv.join("pyvenv.cfg").try_exists()) {
+                    // It's a virtual environment we can remove it
+                    (_, Ok(true)) => true,
+                    // It doesn't exist at all, we should use it without deleting it to avoid TOCTOU bugs
+                    (Ok(false), Ok(false)) => false,
+                    // If it's not a virtual environment, bail
+                    (Ok(true), Ok(false)) => {
+                        // Unless it's empty, in which case we just ignore it
+                        if venv.read_dir().is_ok_and(|mut dir| dir.next().is_none()) {
+                            false
+                        } else {
+                            return Err(ProjectError::InvalidProjectEnvironmentDir(
+                                venv,
+                                "it is not a compatible environment but cannot be recreated because it is not a virtual environment".to_string(),
+                            ));
+                        }
+                    }
+                    // Similarly, if we can't _tell_ if it exists we should bail
+                    (_, Err(err)) | (Err(err), _) => {
                         return Err(ProjectError::InvalidProjectEnvironmentDir(
                             venv,
-                            "it is not a compatible environment but cannot be recreated because it is not a virtual environment".to_string(),
+                            format!("it is not a compatible environment but cannot be recreated because uv cannot determine if it is a virtual environment: {err}"),
                         ));
                     }
+                };
+
+                // Under `--dry-run`, avoid modifying the environment.
+                if dry_run {
+                    let environment = PythonEnvironment::from_interpreter(interpreter);
+                    return Ok(if replace {
+                        Self::Replaced(environment, venv)
+                    } else {
+                        Self::New(environment, venv)
+                    });
                 }
-                // Similarly, if we can't _tell_ if it exists we should bail
-                (_, Err(err)) | (Err(err), _) => {
-                    return Err(ProjectError::InvalidProjectEnvironmentDir(
-                        venv,
-                        format!("it is not a compatible environment but cannot be recreated because uv cannot determine if it is a virtual environment: {err}"),
-                    ));
-                }
-            };
 
-            // Remove the existing virtual environment if it doesn't meet the requirements.
-            if should_remove {
-                match fs_err::remove_dir_all(&venv) {
-                    Ok(()) => {
-                        writeln!(
-                            printer.stderr(),
-                            "Removed virtual environment at: {}",
-                            venv.user_display().cyan()
-                        )?;
+                // Remove the existing virtual environment if it doesn't meet the requirements.
+                if replace {
+                    match fs_err::remove_dir_all(&venv) {
+                        Ok(()) => {
+                            writeln!(
+                                printer.stderr(),
+                                "Removed virtual environment at: {}",
+                                venv.user_display().cyan()
+                            )?;
+                        }
+                        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+                        Err(e) => return Err(e.into()),
                     }
-                    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
-                    Err(e) => return Err(e.into()),
                 }
-            }
 
-            writeln!(
-                printer.stderr(),
-                "Creating virtual environment at: {}",
-                venv.user_display().cyan()
-            )?;
+                writeln!(
+                    printer.stderr(),
+                    "Creating virtual environment at: {}",
+                    venv.user_display().cyan()
+                )?;
+
+                // Determine a prompt for the environment, in order of preference:
+                //
+                // 1) The name of the project
+                // 2) The name of the directory at the root of the workspace
+                // 3) No prompt
+                let prompt = workspace
+                    .pyproject_toml()
+                    .project
+                    .as_ref()
+                    .map(|p| p.name.to_string())
+                    .or_else(|| {
+                        workspace
+                            .install_path()
+                            .file_name()
+                            .map(|f| f.to_string_lossy().to_string())
+                    })
+                    .map(uv_virtualenv::Prompt::Static)
+                    .unwrap_or(uv_virtualenv::Prompt::None);
+
+                let environment = uv_virtualenv::create_venv(
+                    &venv,
+                    interpreter,
+                    prompt,
+                    false,
+                    false,
+                    false,
+                    false,
+                )?;
+
+                if replace {
+                    Ok(Self::Replaced(environment, venv))
+                } else {
+                    Ok(Self::New(environment, venv))
+                }
+            }
+        }
+    }
 
-            // Determine a prompt for the environment, in order of preference:
-            //
-            // 1) The name of the project
-            // 2) The name of the directory at the root of the workspace
-            // 3) No prompt
-            let prompt = workspace
-                .pyproject_toml()
-                .project
-                .as_ref()
-                .map(|p| p.name.to_string())
-                .or_else(|| {
-                    workspace
-                        .install_path()
-                        .file_name()
-                        .map(|f| f.to_string_lossy().to_string())
-                })
-                .map(uv_virtualenv::Prompt::Static)
-                .unwrap_or(uv_virtualenv::Prompt::None);
-
-            Ok(uv_virtualenv::create_venv(
-                &venv,
-                interpreter,
-                prompt,
-                false,
-                false,
-                false,
-                false,
-            )?)
+    /// Convert the [`ProjectEnvironment`] into a [`PythonEnvironment`].
+    pub(crate) fn into_environment(self) -> PythonEnvironment {
+        match self {
+            Self::Existing(environment) => environment,
+            Self::Replaced(environment, ..) => environment,
+            Self::New(environment, ..) => environment,
         }
     }
 }