Environment Manager Discovery Patterns

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

Manager Quick Reference

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: POETRYVIRTUALENVS*
3. Global config: ~/.config/pypoetry/config.toml

Known Issues

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/ (XDGDATAHOME)
• macOS: ~/.local/share/virtualenvs/
• Windows: ~\.virtualenvs\

When WORKON_HOME is set:

• Use $WORKON_HOME/ directly

Environment Variables

Known Issues

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)
• $PYENVROOT/versions/ (if PYENVROOT set)

Windows (pyenv-win):

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

Key Differences: Unix vs Windows

Known Issues

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

Known Issues

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

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;
}