Add VenvUv support and alwaysUseUv setting to control UV usage for virtual environments (#940)

## Overview

This PR implements support for UV-created virtual environments and adds
a new setting to control when UV is used for managing virtual
environments, as requested in the issue.

## Changes

### 1. New Environment Kind: `VenvUv`

Added `venvUv = 'Uv'` to the `NativePythonEnvironmentKind` enum to
represent virtual environments created with UV. This tag comes from
PET's native locator when it detects `uv_version` in the `pyvenv.cfg`
file.

### 2. New Setting: `python-envs.alwaysUseUv`

```json
{
  "python-envs.alwaysUseUv": {
    "type": "boolean",
    "default": true,
    "scope": "machine",
    "description": "When set to true, uv will be used to manage all virtual environments if available. When set to false, uv will only manage virtual environments explicitly created by uv."
  }
}
```

### 3. Smart UV Detection Logic

Introduced a `shouldUseUv()` helper function that determines when to use
UV:

- **VenvUv environments**: Always use UV (if installed), regardless of
the setting
- **Other environments**: Use UV only if `alwaysUseUv` setting is `true`
(if installed)

This ensures that UV-created environments always use UV for management,
while giving users control over whether UV should manage standard venvs.

### 4. Updated Operations

All virtual environment and pip operations now respect the new setting:

- **Environment Discovery**: `findVirtualEnvironments()` and
`resolveVenvPythonEnvironmentPath()` now handle both `Venv` and `Uv`
kinds
- **Environment Creation**: `createWithProgress()` uses the setting to
decide between `uv venv` and `python -m venv`
- **Package Management**: `refreshPipPackagesRaw()` and
`managePackages()` use the setting to decide between `uv pip` and
`python -m pip`

## Behavior

| Environment Type | alwaysUseUv = true | alwaysUseUv = false |
|-----------------|-------------------|---------------------|
| VenvUv (UV-created) | ✅ Use UV | ✅ Use UV |
| Venv (standard) | ✅ Use UV | ❌ Don't use UV |

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: eleanorjboyd <[email protected]>

Author: Copilot

.github/instructions/testing-workflow.instructions.md

@@ -537,6 +537,22 @@ envConfig.inspect
 -   ❌ Tests that don't clean up mocks properly
 -   ❌ Overly complex test setup that's hard to understand
 
+## 🔄 Reviewing and Improving Existing Tests
+
+### Quick Review Process
+
+1. **Read test files** - Check structure and mock setup
+2. **Run tests** - Establish baseline functionality
+3. **Apply improvements** - Use patterns below
+4. **Verify** - Ensure tests still pass
+
+### Common Fixes
+
+-   Over-complex mocks → Minimal mocks with only needed methods
+-   Brittle assertions → Behavior-focused with error messages
+-   Vague test names → Clear scenario descriptions
+-   Missing structure → Mock → Run → Assert pattern
+
 ## 🧠 Agent Learnings
 
 -   Always use dynamic path construction with Node.js `path` module when testing functions that resolve paths against workspace folders to ensure cross-platform compatibility (1)
@@ -551,3 +567,7 @@ envConfig.inspect
 -   When a targeted test run yields 0 tests, first verify the compiled JS exists under `out/test` (rootDir is `src`); absence almost always means the test file sits outside `src` or compilation hasn't run yet (1)
 -   When unit tests fail with VS Code API errors like `TypeError: X is not a constructor` or `Cannot read properties of undefined (reading 'Y')`, check if VS Code APIs are properly mocked in `/src/test/unittests.ts` - add missing Task-related APIs (`Task`, `TaskScope`, `ShellExecution`, `TaskRevealKind`, `TaskPanelKind`) and namespace mocks (`tasks`) following the existing pattern of `mockedVSCode.X = vscodeMocks.vscMockExtHostedTypes.X` (1)
 -   Create minimal mock objects with only required methods and use TypeScript type assertions (e.g., mockApi as PythonEnvironmentApi) to satisfy interface requirements instead of implementing all interface methods when only specific methods are needed for the test (1)
+-   When reviewing existing tests, focus on behavior rather than implementation details in test names and assertions - transform "should return X when Y" into "should [expected behavior] when [scenario context]" (1)
+-   Simplify mock setup by only mocking methods actually used in tests and use `as unknown as Type` for TypeScript compatibility (1)
+-   When testing async functions that use child processes, call the function first to get a promise, then use setTimeout to emit mock events, then await the promise - this ensures proper timing of mock setup versus function execution (1)
+-   Cannot stub internal function calls within the same module after import - stub external dependencies instead (e.g., stub `childProcessApis.spawnProcess` rather than trying to stub `helpers.isUvInstalled` when testing `helpers.shouldUseUv`) because intra-module calls use direct references, not module exports (1)

package.json

@@ -128,6 +128,12 @@
                     "items": {
                         "type": "string"
                     }
+                },
+                "python-envs.alwaysUseUv": {
+                    "type": "boolean",
+                    "description": "%python-envs.alwaysUseUv.description%",
+                    "default": true,
+                    "scope": "machine"
                 }
             }
         },

package.nls.json

@@ -39,5 +39,6 @@
     "python-envs.terminal.deactivate.title": "Deactivate Environment in Current Terminal",
     "python-envs.uninstallPackage.title": "Uninstall Package",
     "python-envs.revealProjectInExplorer.title": "Reveal Project in Explorer",
-    "python-envs.runPetInTerminal.title": "Run Python Environment Tool (PET) in Terminal..."
+    "python-envs.runPetInTerminal.title": "Run Python Environment Tool (PET) in Terminal...",
+    "python-envs.alwaysUseUv.description": "When set to true, uv will be used to manage all virtual environments if available. When set to false, uv will only manage virtual environments explicitly created by uv."
 }

src/managers/builtin/helpers.ts

@@ -1,20 +1,30 @@
-import * as ch from 'child_process';
 import { CancellationError, CancellationToken, LogOutputChannel } from 'vscode';
-import { createDeferred } from '../../common/utils/deferred';
-import { sendTelemetryEvent } from '../../common/telemetry/sender';
+import { spawnProcess } from '../../common/childProcess.apis';
 import { EventNames } from '../../common/telemetry/constants';
+import { sendTelemetryEvent } from '../../common/telemetry/sender';
+import { createDeferred } from '../../common/utils/deferred';
+import { getConfiguration } from '../../common/workspace.apis';
+import { getUvEnvironments } from './uvEnvironments';
+
+let available = createDeferred<boolean>();
+
+/**
+ * Reset the UV installation cache.
+ */
+export function resetUvInstallationCache(): void {
+    available = createDeferred<boolean>();
+}
 
-const available = createDeferred<boolean>();
 export async function isUvInstalled(log?: LogOutputChannel): Promise<boolean> {
     if (available.completed) {
         return available.promise;
     }
     log?.info(`Running: uv --version`);
-    const proc = ch.spawn('uv', ['--version']);
+    const proc = spawnProcess('uv', ['--version']);
     proc.on('error', () => {
         available.resolve(false);
     });
-    proc.stdout.on('data', (d) => log?.info(d.toString()));
+    proc.stdout?.on('data', (d) => log?.info(d.toString()));
     proc.on('exit', (code) => {
         if (code === 0) {
             sendTelemetryEvent(EventNames.VENV_USING_UV);
@@ -24,6 +34,31 @@ export async function isUvInstalled(log?: LogOutputChannel): Promise<boolean> {
     return available.promise;
 }
 
+/**
+ * Determines if uv should be used for managing a virtual environment.
+ * @param log - Optional log output channel for logging operations
+ * @param envPath - Optional environment path to check against UV environments list
+ * @returns True if uv should be used, false otherwise. For UV environments, returns true if uv is installed. For other environments, checks the 'python-envs.alwaysUseUv' setting and uv availability.
+ */
+export async function shouldUseUv(log?: LogOutputChannel, envPath?: string): Promise<boolean> {
+    if (envPath) {
+        // always use uv if the given environment is stored as a uv env
+        const uvEnvs = await getUvEnvironments();
+        if (uvEnvs.includes(envPath)) {
+            return await isUvInstalled(log);
+        }
+    }
+
+    // For other environments, check the user setting
+    const config = getConfiguration('python-envs');
+    const alwaysUseUv = config.get<boolean>('alwaysUseUv', true);
+
+    if (alwaysUseUv) {
+        return await isUvInstalled(log);
+    }
+    return false;
+}
+
 export async function runUV(
     args: string[],
     cwd?: string,
@@ -32,7 +67,7 @@ export async function runUV(
 ): Promise<string> {
     log?.info(`Running: uv ${args.join(' ')}`);
     return new Promise<string>((resolve, reject) => {
-        const proc = ch.spawn('uv', args, { cwd: cwd });
+        const proc = spawnProcess('uv', args, { cwd: cwd });
         token?.onCancellationRequested(() => {
             proc.kill();
             reject(new CancellationError());
@@ -72,7 +107,7 @@ export async function runPython(
 ): Promise<string> {
     log?.info(`Running: ${python} ${args.join(' ')}`);
     return new Promise<string>((resolve, reject) => {
-        const proc = ch.spawn(python, args, { cwd: cwd });
+        const proc = spawnProcess(python, args, { cwd: cwd });
         token?.onCancellationRequested(() => {
             proc.kill();
             reject(new CancellationError());

src/managers/builtin/pipManager.ts

@@ -1,5 +1,6 @@
 import {
     CancellationError,
+    Disposable,
     Event,
     EventEmitter,
     LogOutputChannel,
@@ -18,10 +19,9 @@ import {
     PythonEnvironment,
     PythonEnvironmentApi,
 } from '../../api';
+import { getWorkspacePackagesToInstall } from './pipUtils';
 import { managePackages, refreshPackages } from './utils';
-import { Disposable } from 'vscode-jsonrpc';
 import { VenvManager } from './venvManager';
-import { getWorkspacePackagesToInstall } from './pipUtils';
 
 function getChanges(before: Package[], after: Package[]): { kind: PackageChangeKind; pkg: Package }[] {
     const changes: { kind: PackageChangeKind; pkg: Package }[] = [];

src/managers/builtin/utils.ts

@@ -18,7 +18,7 @@ import {
     NativePythonFinder,
 } from '../common/nativePythonFinder';
 import { shortVersion, sortEnvironments } from '../common/utils';
-import { isUvInstalled, runPython, runUV } from './helpers';
+import { runPython, runUV, shouldUseUv } from './helpers';
 import { parsePipList, PipPackage } from './pipListUtils';
 
 function asPackageQuickPickItem(name: string, version?: string): QuickPickItem {
@@ -139,11 +139,20 @@ export async function refreshPythons(
 }
 
 async function refreshPipPackagesRaw(environment: PythonEnvironment, log?: LogOutputChannel): Promise<string> {
-    const useUv = await isUvInstalled();
+    // Use environmentPath directly for consistency with UV environment tracking
+    const useUv = await shouldUseUv(log, environment.environmentPath.fsPath);
     if (useUv) {
         return await runUV(['pip', 'list', '--python', environment.execInfo.run.executable], undefined, log);
     }
-    return await runPython(environment.execInfo.run.executable, ['-m', 'pip', 'list'], undefined, log);
+    try {
+        return await runPython(environment.execInfo.run.executable, ['-m', 'pip', 'list'], undefined, log);
+    } catch (ex) {
+        log?.error('Error running pip list', ex);
+        log?.info(
+            'Package list retrieval attempted using pip, action can be done with uv if installed and setting `alwaysUseUv` is enabled.',
+        );
+        throw ex;
+    }
 }
 
 export async function refreshPipPackages(
@@ -194,7 +203,8 @@ export async function managePackages(
         throw new Error('Python 2.* is not supported (deprecated)');
     }
 
-    const useUv = await isUvInstalled();
+    // Use environmentPath directly for consistency with UV environment tracking
+    const useUv = await shouldUseUv(manager.log, environment.environmentPath.fsPath);
     const uninstallArgs = ['pip', 'uninstall'];
     if (options.uninstall && options.uninstall.length > 0) {
         if (useUv) {

src/managers/builtin/uvEnvironments.ts

@@ -0,0 +1,52 @@
+import { ENVS_EXTENSION_ID } from '../../common/constants';
+import { getWorkspacePersistentState } from '../../common/persistentState';
+
+/**
+ * Persistent storage key for UV-managed virtual environments.
+ *
+ * This key is used to store a list of environment paths that were created or identified
+ * as UV-managed virtual environments. The stored paths correspond to the
+ * PythonEnvironmentInfo.environmentPath.fsPath values.
+ */
+export const UV_ENVS_KEY = `${ENVS_EXTENSION_ID}:uv:UV_ENVIRONMENTS`;
+
+/**
+ * @returns Array of environment paths (PythonEnvironmentInfo.environmentPath.fsPath values)
+ * that are known to be UV-managed virtual environments
+ */
+export async function getUvEnvironments(): Promise<string[]> {
+    const state = await getWorkspacePersistentState();
+    return (await state.get(UV_ENVS_KEY)) ?? [];
+}
+
+/**
+ * @param environmentPath The environment path (should be PythonEnvironmentInfo.environmentPath.fsPath)
+ * to mark as UV-managed. Duplicates are automatically ignored.
+ */
+export async function addUvEnvironment(environmentPath: string): Promise<void> {
+    const state = await getWorkspacePersistentState();
+    const uvEnvs = await getUvEnvironments();
+    if (!uvEnvs.includes(environmentPath)) {
+        uvEnvs.push(environmentPath);
+        await state.set(UV_ENVS_KEY, uvEnvs);
+    }
+}
+
+/**
+ * @param environmentPath The environment path (PythonEnvironmentInfo.environmentPath.fsPath)
+ * to remove from UV tracking. No-op if path not found.
+ */
+export async function removeUvEnvironment(environmentPath: string): Promise<void> {
+    const state = await getWorkspacePersistentState();
+    const uvEnvs = await getUvEnvironments();
+    const filtered = uvEnvs.filter((path) => path !== environmentPath);
+    await state.set(UV_ENVS_KEY, filtered);
+}
+
+/**
+ * Clears all UV-managed environment paths from the tracking list.
+ */
+export async function clearUvEnvironments(): Promise<void> {
+    const state = await getWorkspacePersistentState();
+    await state.set(UV_ENVS_KEY, []);
+}

src/managers/builtin/venvUtils.ts

@@ -25,9 +25,10 @@ import {
     NativePythonFinder,
 } from '../common/nativePythonFinder';
 import { getShellActivationCommands, shortVersion, sortEnvironments } from '../common/utils';
-import { isUvInstalled, runPython, runUV } from './helpers';
+import { runPython, runUV, shouldUseUv } from './helpers';
 import { getProjectInstallable, PipPackages } from './pipUtils';
 import { resolveSystemPythonEnvironmentPath } from './utils';
+import { addUvEnvironment, removeUvEnvironment, UV_ENVS_KEY } from './uvEnvironments';
 import { createStepBasedVenvFlow } from './venvStepBasedFlow';
 
 export const VENV_WORKSPACE_KEY = `${ENVS_EXTENSION_ID}:venv:WORKSPACE_SELECTED`;
@@ -54,7 +55,7 @@ export interface CreateEnvironmentResult {
 }
 
 export async function clearVenvCache(): Promise<void> {
-    const keys = [VENV_WORKSPACE_KEY, VENV_GLOBAL_KEY];
+    const keys = [VENV_WORKSPACE_KEY, VENV_GLOBAL_KEY, UV_ENVS_KEY];
     const state = await getWorkspacePersistentState();
     await state.clear(keys);
 }
@@ -131,6 +132,10 @@ async function getPythonInfo(env: NativeEnvInfo): Promise<PythonEnvironmentInfo>
         const venvName = env.name ?? getName(env.executable);
         const sv = shortVersion(env.version);
         const name = `${venvName} (${sv})`;
+        let description = undefined;
+        if (env.kind === NativePythonEnvironmentKind.venvUv) {
+            description = l10n.t('uv');
+        }
 
         const binDir = path.dirname(env.executable);
 
@@ -142,7 +147,7 @@ async function getPythonInfo(env: NativeEnvInfo): Promise<PythonEnvironmentInfo>
             shortDisplayName: `${sv} (${venvName})`,
             displayPath: env.executable,
             version: env.version,
-            description: undefined,
+            description: description,
             tooltip: env.executable,
             environmentPath: Uri.file(env.executable),
             iconPath: new ThemeIcon('python'),
@@ -176,7 +181,7 @@ export async function findVirtualEnvironments(
     const envs = data
         .filter((e) => isNativeEnvInfo(e))
         .map((e) => e as NativeEnvInfo)
-        .filter((e) => e.kind === NativePythonEnvironmentKind.venv);
+        .filter((e) => e.kind === NativePythonEnvironmentKind.venv || e.kind === NativePythonEnvironmentKind.venvUv);
 
     for (const e of envs) {
         if (!(e.prefix && e.executable && e.version)) {
@@ -187,6 +192,11 @@ export async function findVirtualEnvironments(
         const env = api.createPythonEnvironmentItem(await getPythonInfo(e), manager);
         collection.push(env);
         log.info(`Found venv environment: ${env.name}`);
+
+        // Track UV environments using environmentPath for consistency
+        if (e.kind === NativePythonEnvironmentKind.venvUv) {
+            await addUvEnvironment(env.environmentPath.fsPath);
+        }
     }
     return collection;
 }
@@ -290,7 +300,7 @@ export async function createWithProgress(
         async () => {
             const result: CreateEnvironmentResult = {};
             try {
-                const useUv = await isUvInstalled(log);
+                const useUv = await shouldUseUv(log, basePython.environmentPath.fsPath);
                 // env creation
                 if (basePython.execInfo?.run.executable) {
                     if (useUv) {
@@ -316,6 +326,10 @@ export async function createWithProgress(
                 const resolved = await nativeFinder.resolve(pythonPath);
                 const env = api.createPythonEnvironmentItem(await getPythonInfo(resolved), manager);
 
+                if (useUv && resolved.kind === NativePythonEnvironmentKind.venvUv) {
+                    await addUvEnvironment(env.environmentPath.fsPath);
+                }
+
                 // install packages
                 if (packages && (packages.install.length > 0 || packages.uninstall.length > 0)) {
                     try {
@@ -435,6 +449,7 @@ export async function removeVenv(environment: PythonEnvironment, log: LogOutputC
             async () => {
                 try {
                     await fsapi.remove(envPath);
+                    await removeUvEnvironment(environment.environmentPath.fsPath);
                     return true;
                 } catch (e) {
                     log.error(`Failed to remove virtual environment: ${e}`);
@@ -459,7 +474,7 @@ export async function resolveVenvPythonEnvironmentPath(
 ): Promise<PythonEnvironment | undefined> {
     const resolved = await nativeFinder.resolve(fsPath);
 
-    if (resolved.kind === NativePythonEnvironmentKind.venv) {
+    if (resolved.kind === NativePythonEnvironmentKind.venv || resolved.kind === NativePythonEnvironmentKind.venvUv) {
         const envInfo = await getPythonInfo(resolved);
         return api.createPythonEnvironmentItem(envInfo, manager);
     }

src/managers/common/nativePythonFinder.ts

@@ -69,6 +69,7 @@ export enum NativePythonEnvironmentKind {
     linuxGlobal = 'LinuxGlobal',
     macXCode = 'MacXCode',
     venv = 'Venv',
+    venvUv = 'Uv',
     virtualEnv = 'VirtualEnv',
     virtualEnvWrapper = 'VirtualEnvWrapper',
     windowsStore = 'WindowsStore',