Add site-packages watchers

api/src/main.ts

@@ -8,6 +8,7 @@ import {
     FileChangeType,
     LogOutputChannel,
     MarkdownString,
+    RelativePattern,
     TaskExecution,
     Terminal,
     TerminalOptions,
@@ -689,6 +690,16 @@ export interface PackageManager {
      */
     getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
 
+    /**
+     * Returns additional filesystem patterns to watch for package install/uninstall changes.
+     *
+     * These patterns are appended to the default site-packages metadata locations.
+     * Implement this for manager-specific locations (for example, conda-meta).
+     *
+     * @param environment - The Python environment whose package paths should be watched.
+     * @returns Relative patterns to watch for package changes.
+     */
+    getPackageWatchTargets?(environment: PythonEnvironment): RelativePattern[];
     /**
      * Event that is fired when packages change.
      */

examples/sample1/src/api.ts

@@ -7,6 +7,7 @@ import {
     FileChangeType,
     LogOutputChannel,
     MarkdownString,
+    RelativePattern,
     TaskExecution,
     Terminal,
     TerminalOptions,
@@ -616,6 +617,17 @@ export interface PackageManager {
      */
     getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
 
+    /**
+     * Returns additional filesystem patterns to watch for package install/uninstall changes.
+     *
+     * These patterns are appended to the default site-packages metadata locations.
+     * Implement this for manager-specific locations (for example, conda-meta).
+     *
+     * @param environment - The Python environment whose package paths should be watched.
+     * @returns Relative patterns to watch for package changes.
+     */
+    getPackageWatchTargets?(environment: PythonEnvironment): RelativePattern[];
+
     /**
      * Event that is fired when packages change.
      */

package.json

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

package.nls.json

@@ -46,5 +46,6 @@
     "python-envs.revealEnvInManagerView.title": "Reveal in Environment Managers View",
     "python-envs.runPetInTerminal.title": "Run Python Environment Tool (PET) in Terminal...",
     "python-envs.managePackageVersion.title": "Manage Package Version",
-    "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."
+    "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.",
+    "python-envs.packageWatchers.description": "When enabled, file system watchers monitor site-packages for install/uninstall changes and automatically refresh the package list. Disable this if you experience performance issues in large workspaces."
 }

src/api.ts

@@ -8,6 +8,7 @@ import type {
     FileChangeType,
     LogOutputChannel,
     MarkdownString,
+    RelativePattern,
     TaskExecution,
     Terminal,
     TerminalOptions,
@@ -684,6 +685,17 @@ export interface PackageManager {
      */
     getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
 
+    /**
+     * Returns additional filesystem patterns to watch for package install/uninstall changes.
+     *
+     * These patterns are appended to the default site-packages metadata locations.
+     * Implement this for manager-specific locations (for example, conda-meta).
+     *
+     * @param environment - The Python environment whose package paths should be watched.
+     * @returns Relative patterns to watch for package changes.
+     */
+    getPackageWatchTargets?(environment: PythonEnvironment): RelativePattern[];
+
     /**
      * Event that is fired when packages change.
      */

src/managers/builtin/main.ts

@@ -4,6 +4,7 @@ import { createSimpleDebounce } from '../../common/utils/debounce';
 import { createFileSystemWatcher, onDidDeleteFiles } from '../../common/workspace.apis';
 import { getPythonApi } from '../../features/pythonApi';
 import { NativePythonFinder } from '../common/nativePythonFinder';
+import { registerPackageWatcherForManager } from '../common/packageWatcher';
 import { PipPackageManager } from './pipPackageManager';
 import { SysPythonManager } from './sysPythonManager';
 import { VenvManager } from './venvManager';
@@ -41,38 +42,8 @@ export async function registerSystemPythonFeatures(
         }),
     );
 
-    const packageDebouncedRefresh = createSimpleDebounce(500, async () => {
-        const projects = await api.getPythonProjects();
-        await Promise.all(
-            projects.map(async (project) => {
-                const env = await api.getEnvironment(project.uri);
-                if (!env) {
-                    return;
-                }
-                try {
-                    await api.refreshPackages(env);
-                } catch (ex) {
-                    log.error(
-                        `Failed to refresh packages for environment ${env.envId}: ${ex instanceof Error ? ex.message : String(ex)}`,
-                    );
-                }
-            }),
-        );
-    });
-    const packageWatcher = createFileSystemWatcher(
-        '**/site-packages/*.dist-info/METADATA',
-        false, // don't ignore create events    (pip install)
-        true, // ignore change events          (content changes in METADATA don't affect package list)
-        false, // don't ignore delete events    (pip uninstall)
-    );
     disposables.push(
-        packageDebouncedRefresh,
-        packageWatcher,
-        packageWatcher.onDidCreate(() => {
-            packageDebouncedRefresh.trigger();
-        }),
-        packageWatcher.onDidDelete(() => {
-            packageDebouncedRefresh.trigger();
-        }),
+        registerPackageWatcherForManager(envManager, pkgManager, log),
+        registerPackageWatcherForManager(venvManager, pkgManager, log),
     );
 }

src/managers/common/packageWatcher.ts

@@ -0,0 +1,130 @@
+import * as path from 'path';
+import { Disposable, LogOutputChannel, RelativePattern } from 'vscode';
+import { EnvironmentManager, PackageManager, PythonEnvironment } from '../../api';
+import { createSimpleDebounce } from '../../common/utils/debounce';
+import { createFileSystemWatcher, getConfiguration } from '../../common/workspace.apis';
+
+/**
+ * Derives the file system watch targets for a given Python environment.
+ *
+ * Targets include site-packages `.dist-info/METADATA` files for pip-style installs.
+ *
+ * @param env - The Python environment to derive watch targets for.
+ * @returns An array of RelativePattern objects, one per discoverable package location.
+ *          Empty if the environment has no `sysPrefix` or discoverable paths.
+ */
+function getDefaultPackageWatchTargets(env: PythonEnvironment): RelativePattern[] {
+    if (!env.sysPrefix) {
+        return [];
+    }
+    return process.platform === 'win32'
+        ? [new RelativePattern(path.join(env.sysPrefix, 'Lib'), 'site-packages/**/*.dist-info/METADATA')] // Windows
+        : [new RelativePattern(path.join(env.sysPrefix, 'lib'), 'python*/site-packages/**/*.dist-info/METADATA')]; // Unix-like
+}
+
+/**
+ * Creates a file system watcher for package changes in a single environment.
+ *
+ * Monitors default site-packages locations and any manager-specific extra locations
+ * for install/uninstall operations.
+ * and triggers a debounced package refresh when changes are detected.
+ *
+ * @param env - The Python environment to watch.
+ * @param packageManager - The package manager to call refresh on when changes occur.
+ * @param log - Logger for diagnostic messages.
+ * @returns A disposable that removes the watcher when disposed.
+ */
+export function watchPackageChangesForEnvironment(
+    env: PythonEnvironment,
+    packageManager: PackageManager,
+    log: LogOutputChannel,
+): Disposable {
+    // Watch targets
+    const watchTargets = [
+        ...getDefaultPackageWatchTargets(env),
+        ...(packageManager.getPackageWatchTargets?.(env) ?? []),
+    ];
+    if (watchTargets.length === 0) {
+        log.debug(`No watch targets for environment ${env.envId.id}`);
+        return new Disposable(() => undefined);
+    }
+    // Debounced refresh function
+    const debouncedRefresh = createSimpleDebounce(500, async () => {
+        log.debug(`Package change detected for environment ${env.envId.id}, refreshing packages.`);
+        packageManager.refresh(env).catch((ex) => {
+            log.error(
+                `Failed to refresh packages for environment ${env.envId.id}: ${ex instanceof Error ? ex.message : String(ex)}`,
+            );
+        });
+    });
+    // Create watchers
+    const disposables: Disposable[] = [debouncedRefresh];
+    const trigger = debouncedRefresh.trigger.bind(debouncedRefresh);
+    for (const target of watchTargets) {
+        const watcher = createFileSystemWatcher(
+            target,
+            false, // create   -> install
+            true, // change   -> ignore
+            false, // delete   -> uninstall
+        );
+        disposables.push(
+            watcher,
+            watcher.onDidCreate(trigger),
+            watcher.onDidDelete(trigger),
+        );
+    }
+
+    return new Disposable(() => disposables.forEach((d) => d.dispose()));
+}
+
+/**
+ * Registers automatic file system watchers for the active environment managed by a given manager.
+ *
+ * Creates per-environment watchers that are attached when the active environment changes
+ * and detached when it changes to a different environment. Ensures package changes
+ * (installs/uninstalls) in the active environment are detected and trigger a refresh.
+ *
+ * @param envManager - The environment manager whose active environment should be watched.
+ * @param packageManager - The package manager to call refresh on when changes occur.
+ * @param log - Logger for diagnostic and error messages.
+ * @returns A disposable that removes all watchers and subscriptions when disposed.
+ */
+export function registerPackageWatcherForManager(
+    envManager: EnvironmentManager,
+    packageManager: PackageManager,
+    log: LogOutputChannel,
+): Disposable {
+    const packageWatchersEnabled = getConfiguration('python-envs').get<boolean>('packageWatchers', true);
+    if (!packageWatchersEnabled) {
+        return new Disposable(() => undefined);
+    }
+
+    // One watcher per environment id.
+    const watchers = new Map<string, Disposable>();
+
+    const addWatcher = (env: PythonEnvironment): void => {
+        if (!watchers.has(env.envId.id)) {
+            watchers.set(env.envId.id, watchPackageChangesForEnvironment(env, packageManager, log));
+        }
+    };
+
+    const removeWatcher = (envId: string): void => {
+        watchers.get(envId)?.dispose();
+        watchers.delete(envId);
+    };
+
+    const envChangeDisposable = envManager.onDidChangeEnvironment?.((changes) => {
+        if (changes.new) {
+            addWatcher(changes.new);
+        }
+        if (changes.old && changes.old.envId.id !== changes.new?.envId.id) {
+            removeWatcher(changes.old.envId.id);
+        }
+    });
+
+    return new Disposable(() => {
+        envChangeDisposable?.dispose();
+        watchers.forEach((watcher) => watcher.dispose());
+        watchers.clear();
+    });
+}

src/managers/conda/condaPackageManager.ts

@@ -1,5 +1,6 @@
 import type { Pep440Version } from '@renovatebot/pep440';
 import { explain as parse, rcompare } from '@renovatebot/pep440';
+import * as path from 'path';
 import {
     CancellationError,
     Disposable,
@@ -8,6 +9,7 @@ import {
     LogOutputChannel,
     MarkdownString,
     ProgressLocation,
+    RelativePattern,
 } from 'vscode';
 import {
     DidChangePackagesEventArgs,
@@ -197,6 +199,14 @@ export class CondaPackageManager implements PackageManager, Disposable {
         }
     }
 
+    getPackageWatchTargets(environment: PythonEnvironment): RelativePattern[] {
+        if (!environment.sysPrefix) {
+            return [];
+        }
+
+        return [new RelativePattern(path.join(environment.sysPrefix, 'conda-meta'), '**/*.json')];
+    }
+
     dispose() {
         this._onDidChangePackages.dispose();
         this.packages.clear();

src/managers/poetry/main.ts

@@ -4,6 +4,7 @@ import { traceInfo } from '../../common/logging';
 import { getPythonApi } from '../../features/pythonApi';
 import { PythonProjectManager } from '../../internal.api';
 import { NativePythonFinder } from '../common/nativePythonFinder';
+import { registerPackageWatcherForManager } from '../common/packageWatcher';
 import { PoetryManager } from './poetryManager';
 import { PoetryPackageManager } from './poetryPackageManager';
 
@@ -24,5 +25,6 @@ export async function registerPoetryFeatures(
         pkgManager,
         api.registerEnvironmentManager(envManager),
         api.registerPackageManager(pkgManager),
+        registerPackageWatcherForManager(envManager, pkgManager, outputChannel),
     );
 }