microsoft/python-manager-discovery

Environment Manager Discovery Patterns

This skill documents manager-specific discovery patterns, environment variable precedence, and known issues.

Manager Quick Reference

| Manager | Config Files | Cache Location | Key Env Vars | | ------- | ---------------------------------------------- | ------------------------ | --------------------------------------------------- | | Poetry | poetry.toml, pyproject.toml, config.toml | Platform-specific | POETRY_VIRTUALENVS_IN_PROJECT, POETRY_CACHE_DIR | | Pipenv | Pipfile, Pipfile.lock | XDG or WORKON_HOME | WORKON_HOME, XDG_DATA_HOME | | Pyenv | .python-version, versions/ | ~/.pyenv/ or pyenv-win | PYENV_ROOT, PYENV_VERSION | | Conda | environment.yml, conda-meta/ | Registries + paths | CONDA_PREFIX, CONDA_DEFAULT_ENV | | venv | pyvenv.cfg | In-project | None |

---

Poetry

Discovery Locations

Virtualenvs cache (default):

• Windows: %LOCALAPPDATA%\pypoetry\Cache\virtualenvs
• macOS: ~/Library/Caches/pypoetry/virtualenvs
• Linux: ~/.cache/pypoetry/virtualenvs

In-project (when enabled):

• .venv/ in project root

Config Precedence (highest to lowest)

1. Local config: poetry.toml in project root
2. Environment variables: POETRY_VIRTUALENVS_*
3. Global config: ~/.config/pypoetry/config.toml

Known Issues

| Issue | Description | Fix | | ------------------------- | ----------------------------------------------- | -------------------------------- | | {cache-dir} placeholder | Not resolved in paths from config | Resolve placeholder before use | | Wrong default path | Windows/macOS differ from Linux | Use platform-specific defaults | | In-project detection | POETRY_VIRTUALENVS_IN_PROJECT must be checked | Check env var first, then config |

Code Pattern

async function getPoetryVirtualenvsPath(): Promise<string> {
    // 1. Check environment variable first
    const envVar = process.env.POETRY_VIRTUALENVS_PATH;
    if (envVar) return envVar;

    // 2. Check local poetry.toml
    const localConfig = await readPoetryToml(projectRoot);
    if (localConfig?.virtualenvs?.path) {
        return resolvePoetryPath(localConfig.virtualenvs.path);
    }

    // 3. Use platform-specific default
    return getDefaultPoetryCache();
}

function resolvePoetryPath(configPath: string): string {
    // Handle {cache-dir} placeholder
    if (configPath.includes('{cache-dir}')) {
        const cacheDir = getDefaultPoetryCache();
        return configPath.replace('{cache-dir}', cacheDir);
    }
    return configPath;
}

---

Pipenv

Discovery Locations

Default:

• Linux: ~/.local/share/virtualenvs/ (XDG_DATA_HOME)
• macOS: ~/.local/share/virtualenvs/
• Windows: ~\.virtualenvs\

When WORKON_HOME is set:

• Use $WORKON_HOME/ directly

Environment Variables

| Var | Purpose | | ------------------------ | ---------------------------- | | WORKON_HOME | Override virtualenv location | | XDG_DATA_HOME | Base for Linux default | | PIPENV_VENV_IN_PROJECT | Create .venv/ in project |

Known Issues

| Issue | Description | Fix | | ----------------------------- | ------------------- | ---------------------------- | | Missing WORKON_HOME support | Env var not checked | Read env var before defaults | | Missing XDG_DATA_HOME support | Not used on Linux | Check XDG spec |

Code Pattern

function getPipenvVirtualenvsPath(): string {
    // Check WORKON_HOME first
    if (process.env.WORKON_HOME) {
        return process.env.WORKON_HOME;
    }

    // Check XDG_DATA_HOME on Linux
    if (process.platform === 'linux') {
        const xdgData = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
        return path.join(xdgData, 'virtualenvs');
    }

    // Windows/macOS defaults
    return path.join(os.homedir(), '.virtualenvs');
}

---

PyEnv

Discovery Locations

Unix:

• ~/.pyenv/versions/ (default)
• $PYENV_ROOT/versions/ (if PYENV_ROOT set)

Windows (pyenv-win):

• %USERPROFILE%\.pyenv\pyenv-win\versions\
• Different directory structure than Unix!

Key Differences: Unix vs Windows

| Aspect | Unix | Windows (pyenv-win) | | ------- | ----------------- | --------------------------------------- | | Command | pyenv | pyenv.bat | | Root | ~/.pyenv/ | %USERPROFILE%\.pyenv\pyenv-win\ | | Shims | ~/.pyenv/shims/ | %USERPROFILE%\.pyenv\pyenv-win\shims\ |

Known Issues

| Issue | Description | Fix | | ---------------------------------- | ------------------------------------------ | ---------------------------------- | | path.normalize() vs path.resolve() | Windows drive letter missing | Use path.resolve() on both sides | | Wrong command on Windows | Looking for pyenv instead of pyenv.bat | Check for .bat extension |

Code Pattern

function getPyenvRoot(): string {
    if (process.env.PYENV_ROOT) {
        return process.env.PYENV_ROOT;
    }

    if (process.platform === 'win32') {
        // pyenv-win uses different structure
        return path.join(os.homedir(), '.pyenv', 'pyenv-win');
    }

    return path.join(os.homedir(), '.pyenv');
}

function getPyenvVersionsPath(): string {
    const root = getPyenvRoot();
    return path.join(root, 'versions');
}

// Use path.resolve() for comparisons!
function comparePyenvPaths(pathA: string, pathB: string): boolean {
    return path.resolve(pathA) === path.resolve(pathB);
}

---

Conda

Discovery Locations

Environment locations:

• Base install envs/ directory
• ~/.conda/envs/
• Paths in ~/.condarc envs_dirs

Windows Registry:

• HKCU\Software\Python\ContinuumAnalytics\
• HKLM\SOFTWARE\Python\ContinuumAnalytics\

Shell Activation

| Shell | Activation Command | | ---------- | -------------------------------------- | | bash, zsh | source activate envname | | fish | conda activate envname (NOT source!) | | PowerShell | conda activate envname | | cmd | activate.bat envname |

Known Issues

| Issue | Description | Fix | | --------------------- | ----------------------- | -------------------------- | | Fish shell activation | Uses bash-style command | Use fish-compatible syntax | | Registry paths | May be stale/invalid | Verify paths exist | | Base vs named envs | Different activation | Check if activating base |

Code Pattern

function getCondaActivationCommand(shell: ShellType, envName: string): string {
    switch (shell) {
        case 'fish':
            // Fish uses different syntax!
            return `conda activate ${envName}`;
        case 'cmd':
            return `activate.bat ${envName}`;
        case 'powershell':
            return `conda activate ${envName}`;
        default:
            // bash, zsh
            return `source activate ${envName}`;
    }
}

---

venv

Discovery

Identification:

• Look for pyvenv.cfg file in directory
• Contains home and optionally version keys

Version Extraction Priority

1. version field in pyvenv.cfg
2. Parse from home path (e.g., Python311)
3. Spawn Python executable (last resort)

Code Pattern

async function getVenvVersion(venvPath: string): Promise<string | undefined> {
    const cfgPath = path.join(venvPath, 'pyvenv.cfg');

    try {
        const content = await fs.readFile(cfgPath, 'utf-8');
        const lines = content.split('\n');

        for (const line of lines) {
            const [key, value] = line.split('=').map((s) => s.trim());
            if (key === 'version') {
                return value;
            }
        }

        // Fall back to parsing home path
        const homeLine = lines.find((l) => l.startsWith('home'));
        if (homeLine) {
            const home = homeLine.split('=')[1].trim();
            const match = home.match(/(\d+)\.(\d+)/);
            if (match) {
                return `${match[1]}.${match[2]}`;
            }
        }
    } catch {
        // Config file not found or unreadable
    }

    return undefined;
}

---

PET Server (Native Finder)

JSON-RPC Communication

The PET server is a Rust-based locator that communicates via JSON-RPC over stdio.

Known Issues

| Issue | Description | Fix | | ------------------- | -------------------------------- | ----------------------------- | | No timeout | JSON-RPC can hang forever | Add Promise.race with timeout | | Silent spawn errors | Extension continues without envs | Surface spawn errors to user | | Resource leaks | Worker pool not cleaned up | Dispose on deactivation | | Type guard missing | Response types not validated | Add runtime type checks | | Cache key collision | Paths normalize to same key | Use consistent normalization |

Code Pattern

async function fetchFromPET<T>(method: string, params: unknown): Promise<T> {
    const timeout = 30000; // 30 seconds

    const result = await Promise.race([
        this.client.request(method, params),
        new Promise<never>((_, reject) => setTimeout(() => reject(new Error('PET server timeout')), timeout)),
    ]);

    // Validate response type
    if (!isValidResponse<T>(result)) {
        throw new Error(`Invalid response from PET: ${JSON.stringify(result)}`);
    }

    return result;
}