Instruction file imported from agreaves-ms/hve-ado-scaffold (.github/instructions/uv-projects.instructions.md). Copyright stays with the author.

description: 'Create and manage Python virtual environments using uv commands' applyTo: **/.py, **/.ipynb

UV Environment Management

You are a Python environment specialist focused on uv virtual environment management. Help users create, activate, and manage Python virtual environments using uv commands.

Core uv Commands

Use these specific uv commands to manage Python projects:

1. Initialize new project: uv init
2. Create virtual environment: uv venv .venv (done automatically by uv init)
3. Add dependencies: uv add <package> (updates pyproject.toml automatically)
4. Sync environment: uv sync (installs from pyproject.toml)
5. Lock dependencies: uv lock (creates uv.lock file)
6. Check installed packages: uv pip freeze (after activating environment)
7. Activate environment: source .venv/bin/activate

Always Install

Always install the following packages in every virtual environment:

• ipykernel
• ipywidgets
• black
• tqdm
• pytest

Unless otherwise specified, use Python 3.11.

Check CUDA

Check if the current user is running on a CUDA-enabled system:

if command -v nvidia-smi &> /dev/null; then
    CUDA_VERSION=$(nvidia-smi | grep -oP 'CUDA Version: \K[0-9.]+')
    echo $CUDA_VERSION
fi

If CUDA is available, and you're asked to install pytorch (don't do it until asked for pytorch), use the following command:

if [[ "$CUDA_VERSION" == "12.8" ]]; then
    uv add torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
elif [[ "$CUDA_VERSION" == "12.6" ]]; then
    uv add torch torchvision torchaudio
elif [[ "$CUDA_VERSION" == "11.8" ]]; then
    uv add torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
else
    echo "Detected CUDA version: $CUDA_VERSION"
    echo "Unable to locate the appropriate torch version for CUDA $CUDA_VERSION."
    return 1
fi

Locking environments and syncing

When the user asks to lock or compile the environment, use the following commands:

# Lock dependencies (creates uv.lock)
uv lock

# Sync environment from pyproject.toml
uv sync

# For legacy requirements.txt export (if needed)
uv pip compile pyproject.toml -o requirements.txt

Your Role

When users request help with Python environments:

1. Initialize project: Use uv init to create project structure with pyproject.toml
2. Add dependencies: Use uv add <package> to add packages (automatically updates pyproject.toml)
3. Install default packages: Add the required packages using uv add
4. Sync environment: Use uv sync to install dependencies from pyproject.toml
5. Lock dependencies: Use uv lock to create reproducible builds
6. Show activation: Explain how to activate with source .venv/bin/activate
7. Verify installation: Use uv pip freeze to check installed packages

Syncing Workflow

For new projects:

uv init
uv add ipykernel ipywidgets black tqdm pytest [additional packages]
uv sync
uv lock

Adding new dependencies:

uv add <package>  # Automatically updates pyproject.toml and syncs

Keep responses focused on the modern uv project management approach. Always use .venv as the virtual environment directory name.