Skill: cikichen/python-venv (version 1.2.0)

--- name: python-venv description: "Python environment management skill. Automatically detect project type and existing environments, recommend based on popularity. Minimize interruptions, only ask when necessary." --- # Python Environment Management Skill ## Core Principles 1. **Reuse Existing Environments** - Don't recreate, reuse existing virtual environments 2. **Use Project-Type Decision** - Auto-select based on lock files 3. **Recommend by Popularity** - uv > pip > conda > venv 4. **Minimize Interruption** - Only ask when necessary --- ## Tool Popularity Ranking | Priority | Tool | Best For | |----------|------|----------| | 🥇 | uv | New projects, fast installs | | 🥈 | pip | Compatibility first | | 🥉 | conda | Data science, specific versions | | 4 | venv | Built-in, no extra install | | 5 | poetry | Existing poetry.lock | | 6 | pipenv | Existing Pipfile (declining) | --- ## Decision Flow ``` ┌─────────────────────────────────────┐ │ Detect project dependency files │ └─────────────────────────────────────┘ ↓ ┌─────────┴─────────┐ ↓ ↓ Clear decision Unclear ↓ ↓ Use directly Detect existing env ↓ ┌─────┴─────┐ ↓ ↓ Has env No env ↓ ↓ Reuse Assess complexity ↓ ┌─────────┴─────────┐ ↓ ↓ Simple task Needs deps ↓ ↓ System Python Recommend uv/conda ``` --- ## 1. Clear Decisions (Execute Directly, No Ask) When these files are detected, use the corresponding tool directly: | Detected File | Execute | |--------------|---------| | `uv.lock` exists | `uv sync` or `uv pip install -r requirements.txt` | | `poetry.lock` exists | `poetry install` | | `environment.yml` exists | `conda env create -f environment.yml` | | `Pipfile.lock` exists | `pipenv install` | --- ## 2. Detect Existing Environments (Reuse First) ```bash # Priority: uv venv > conda > venv # 2.1 Detect uv virtual environment ls -la .venv/ 2>/dev/null && uv pip list 2>/dev/null | head -3 # 2.2 Detect conda environment conda info --envs 2>/dev/null | grep "*" || echo $CONDA_PREFIX # 2.3 Detect standard venv ls -la venv/ .venv/ env/ 2>/dev/null # 2.4 If exists → Reuse (activate and run commands) ``` **Reuse Example:** ``` Detected existing .venv/ directory → Activate: source .venv/bin/activate → Run: uv pip install <package> ``` --- ## 3. When Unclear (Assess Complexity) | Scenario | Action | |----------|--------| | Stdlib only, no 3rd party | System Python (python3) | | Simple pip install test | System Python (temp) | | Has requirements.txt | Recommend uv > pip > venv | | Has pyproject.toml | Recommend uv > pip | | Multi-file project, needs isolation | Recommend uv | --- ## 4. When to Ask User (Only These Cases) ✅ **Ask:** 1. Empty project + first dependency install → Ask which tool 2. Both requirements.txt + pyproject.toml → Ask which to use 3. User explicitly wants different tool → e.g., "I want conda" ❌ **Don't Ask:** - Has uv.lock but user didn't specify - Has .venv/ directory - Regular pip install task --- ## 5. Recommended Tool (No Clear Directive) ``` First: uv ├── uv venv (create) ├── uv pip install (install) └── uv sync (sync) Backup: pip ├── python3 -m venv .venv └── pip install Special: conda ├── conda create -n envname python=x.x └── conda env create ``` --- ## Detection Commands ```bash # Check available tools which uv which conda which pip which python3 # Check project files ls -la *.lock pyproject.toml requirements.txt environment.yml Pipfile 2>/dev/null # Check existing environments ls -la .venv/ venv/ env/ 2>/dev/null conda info --envs 2>/dev/null # Check current environment echo $VIRTUAL_ENV echo $CONDA_PREFIX ``` --- ## Interaction Examples (Only When Needed) ``` 🔍 Detection result: - Project file: pyproject.toml - Existing env: None - Recommended: uv (fastest) Running: uv pip install <package> ``` ``` 🔍 Detection result: - Project file: requirements.txt - Existing env: None - Recommended: uv Available options: 1) uv (recommended) - faster 2) pip - better compatibility 3) venv - uses stdlib 4) conda - if specific version needed Enter option or press Enter to use recommended: ``` --- ## Quick Command Reference | Action | uv | pip | conda | venv | |--------|-----|-----|-------|------| | Create env | `uv venv` | - | `conda create` | `python3 -m venv` | | Install pkg | `uv pip install` | `pip install` | `conda install` | `pip install` | | Install deps | `uv sync` | `pip install -r` | `conda env create` | `pip install -r` | | Activate | (auto) | (auto) | `conda activate` | `source venv/bin/activate` | --- ## Core Principle **"Do more, ask less"** - Execute directly when you can determine, only ask when truly unclear.

path: references/patterns.md
content: # Python Virtual Environment - Common Patterns

## User Choice Pattern (Before Creating venv)

Before creating a new virtual environment, always ask the user:

```
No existing virtual environment found. Choose an option:
1. Create new venv in current directory (.venv) [recommended]
2. Use system Python directly
3. Create venv at custom path
```

Then proceed based on their choice.

## Setup Methods

### uv (Recommended - Faster)

```bash
# Create virtual environment
uv venv

# Create at custom path
uv venv /path/to/my-venv

# Activate (Linux/macOS)
source .venv/bin/activate
source /path/to/my-venv/bin/activate

# Activate (Windows PowerShell)
.venv\Scripts\Activate.ps1
C:\path\to\venv\Scripts\Activate.ps1

# Activate (Windows CMD)
.venv\Scripts\activate.bat
C:\path\to\venv\Scripts\activate.bat

# Install packages
uv pip install <package>

# Install from file
uv pip install -r requirements.txt
uv pip install -e .
```

### Standard venv (Fallback if uv not installed)

```bash
# Create virtual environment
python3 -m venv .venv

# Create at custom path
python3 -m venv /path/to/my-venv

# Activate (Linux/macOS)
source .venv/bin/activate
source /path/to/my-venv/bin/activate

# Activate (Windows PowerShell)
.venv\Scripts\Activate.ps1
C:\path\to\venv\Scripts\Activate.ps1

# Activate (Windows CMD)
.venv\Scripts\activate.bat
C:\path\to\venv\Scripts\activate.bat

# Install packages
pip install <package>

# Install from file
pip install -r requirements.txt
pip install -e .
```

### Conda/Mamba

```bash
# Create environment
conda create -n myenv python=3.11

# Activate
conda activate myenv

# Install packages
conda install <package>
# or
pip install <package>
```

## Common Shell Patterns

### Standard Pattern (Linux/macOS) - Reuse or Create with Fallback

```bash
# Find existing venv or create new one (uv with fallback to venv)
if [ -d .venv ]; then
    source .venv/bin/activate
elif [ -d venv ]; then
    source venv/bin/activate
elif [ -d env ]; then
    source env/bin/activate
elif command -v uv &> /dev/null; then
    uv venv && source .venv/bin/activate
else
    python3 -m venv .venv && source .venv/bin/activate
fi
```

### One-liner (Linux/macOS)

```bash
# Quick version: check .venv, fallback to create
[ -d .venv ] && source .venv/bin/activate || { command -v uv &>/dev/null && uv venv || python3 -m venv .venv; source .venv/bin/activate; }
```

### Windows PowerShell

```powershell
# Find existing venv or create new one
if (Test-Path .venv) { .\.venv\Scripts\Activate.ps1 }
elseif (Test-Path venv) { .\venv\Scripts\Activate.ps1 }
else {
    # Ask user for choice if auto-creation is not desired
    # If creating new venv at default path:
    if (Get-Command uv -ErrorAction SilentlyContinue) { uv venv; .\.venv\Scripts\Activate.ps1 }
    else { python -m venv .venv; .\.venv\Scripts\Activate.ps1 }
}
```

## Running a Python Script

```bash
# Activate existing or create new
[ -d .venv ] && source .venv/bin/activate || { command -v uv &>/dev/null && uv venv || python3 -m venv .venv; source .venv/bin/activate; }

# Install dependencies (check both requirements.txt and pyproject.toml)
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f pyproject.toml ] && pip install -e .

# Run script
python script.py
```

## Verification

### Check if venv is Active

```bash
# Should show path containing .venv, venv, or env
which python

# Or check VIRTUAL_ENV environment variable
echo $VIRTUAL_ENV
```

### Check if Conda Environment is Active

```bash
# Check CONDA_PREFIX
echo $CONDA_PREFIX

# List all conda environments
conda info --envs
```

## Forbidden Actions

- Using `pip install` with system Python (always use venv)
- Installing packages globally
- Assuming third-party packages are available without explicit installation
- Overwriting existing virtual environment without checking first

## Allowed Without venv

- `python3 -c "print('hello')"`
- `python3 -c "import os; print(os.getcwd())"`
- `python3 --version`
- Any stdlib-only one-liner


path: references/troubleshooting.md
content: # Python Virtual Environment - Troubleshooting

## Creating Virtual Environment at Custom Path

If user chooses custom path:

```bash
# With uv
uv venv /path/to/my-venv
source /path/to/my-venv/bin/activate

# With standard venv
python3 -m venv /path/to/my-venv
source /path/to/my-venv/bin/activate
```

Windows:

```powershell
# With uv
uv venv C:\path\to\venv
C:\path\to\venv\Scripts\Activate.ps1

# With standard venv
python -m venv C:\path\to\venv
C:\path\to\venv\Scripts\Activate.ps1
```

## Corrupted Virtual Environment

If venv is broken (import errors, missing packages after install):

```bash
# Remove and recreate
rm -rf .venv
uv venv && source .venv/bin/activate
# or
python3 -m venv .venv && source .venv/bin/activate
```

Windows (PowerShell):

```powershell
Remove-Item -Recurse -Force .venv
uv venv; .\.venv\Scripts\Activate.ps1
# or
python -m venv .venv; .\.venv\Scripts\Activate.ps1
```

## Wrong Python Version

```bash
# Specify Python version with uv
uv venv --python 3.11

# Or with standard venv
python3.11 -m venv .venv
```

Available Python versions:

```bash
# List available Python versions with uv
uv python list

# Find installed Python versions
which python3.11
ls /usr/bin/python*
```

## Permission Denied on Windows

Run PowerShell as Administrator, or:

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

## WSL (Windows Subsystem for Linux)

Use Linux commands in WSL:

```bash
# Same as Linux/macOS
source .venv/bin/activate

# Create venv
uv venv
# or
python3 -m venv .venv
```

**Important**: Don't mix Windows venv with WSL. Create separate venv for each environment.

## Common Issues

### Packages not found after activation

Check you're using the correct Python:

```bash
which python
echo $VIRTUAL_ENV
```

The path should contain your venv directory.

### Python version mismatch

Create venv with specific Python version:

```bash
# First verify Python is installed
python3.11 --version

# Then create venv
python3.11 -m venv .venv
# or with uv
uv venv --python 3.11
```

### uv not installed

Install uv:

```bash
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Then
uv venv
```

Fallback: Use standard venv instead.

### Activation not working on Windows

PowerShell execution policy may be blocking:

```powershell
# Check current policy
Get-ExecutionPolicy

# Allow script execution for current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

Or use CMD instead:

```cmd
.venv\Scripts\activate.bat
```

### Virtual environment location issues

Keep `.venv` directory in:
- Project root (recommended)
- Custom path of user's choice

Avoid:
- System directories (/usr/local, C:\Windows)
- Network drives (slow)
- Paths with spaces or special characters

### Dependencies installation fails

Check project type and use appropriate command:

| File | Correct Command |
|------|-----------------|
| `requirements.txt` | `pip install -r requirements.txt` |
| `pyproject.toml` only | `pip install -e .` |
| `pyproject.toml` + `poetry.lock` | `poetry install` |
| `pyproject.toml` + `uv.lock` | `uv sync` |

Make sure to activate venv before installing.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)