Agent-Skills.md

Agent Skills: UV Management

Quick reference for uv (fast Python package manager) operations to save tokens. Use when creating virtual environments, installing packages, managing dependencies, or when user asks about uv commands. Provides concise patterns for Python project setup and package management.

UncategorizedID: dudusoar/vrp-toolkit/manage-python-env

Repository

dudusoar/vrp-toolkit
dudusoar
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/dudusoar/VRP-Toolkit/tree/HEAD/.claude/skills/manage-python-env

Skill Files

Browse the full folder contents for manage-python-env.

Download Skill

Loading file tree…

.claude/skills/manage-python-env/SKILL.md

Skill Metadata

Name
manage-python-env
Description
Quick reference for uv (fast Python package manager) operations to save tokens. Use when creating virtual environments, installing packages, managing dependencies, or when user asks about uv commands. Provides concise patterns for Python project setup and package management.

UV Management

Quick reference for uv - the fast Python package installer and environment manager.

Installation

Install UV

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

# Or with pip
pip install uv

# Verify installation
uv --version

Project Initialization

Create New Project

# Initialize new project
uv init project-name

# Initialize in current directory
uv init

# With specific Python version
uv init --python 3.11

Project Structure Created

project-name/
├── pyproject.toml    # Project configuration
├── .python-version   # Python version specification
└── src/
    └── project_name/
        └── __init__.py

Virtual Environment

Create Virtual Environment

# Create venv (automatic with uv)
uv venv

# With specific Python version
uv venv --python 3.11

# With custom name
uv venv .venv-custom

# Activate (same as regular venv)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Python Version Management

# List available Python versions
uv python list

# Install specific Python version
uv python install 3.11

# Pin Python version for project
uv python pin 3.11

Package Management

Install Packages

# Install single package
uv pip install package-name

# Install specific version
uv pip install package-name==1.2.3

# Install from requirements.txt
uv pip install -r requirements.txt

# Install from pyproject.toml
uv pip install -e .

# Install development dependencies
uv pip install -e ".[dev]"

Add Dependencies (Modern Way)

# Add package to project
uv add numpy

# Add with version constraint
uv add "numpy>=1.24,<2.0"

# Add multiple packages
uv add numpy pandas matplotlib

# Add as dev dependency
uv add --dev pytest black ruff

# Add from git
uv add git+https://github.com/user/repo.git

Remove Packages

# Remove package
uv remove package-name

# Remove dev dependency
uv remove --dev pytest

Update Packages

# Update single package
uv pip install --upgrade package-name

# Update all packages
uv pip install --upgrade -r requirements.txt

# Sync dependencies (recommended)
uv sync

Dependency Management

Lock Dependencies

# Generate lock file
uv lock

# Lock and sync
uv lock --sync

Export Requirements

# Export to requirements.txt
uv pip freeze > requirements.txt

# Export from pyproject.toml
uv export --format requirements-txt > requirements.txt

Running Commands

Run Python

# Run Python script
uv run python script.py

# Run module
uv run -m module_name

# Run with arguments
uv run python script.py --arg value

Run Tools

# Run pytest
uv run pytest

# Run black
uv run black .

# Run ruff
uv run ruff check .

# Run any tool
uv run tool-name [args]

VRP Project Setup

Initial Project Setup

# 1. Create project directory
mkdir vrp-toolkit
cd vrp-toolkit

# 2. Initialize with uv
uv init

# 3. Create virtual environment
uv venv

# 4. Activate environment
source .venv/bin/activate

# 5. Install core dependencies
uv add numpy pandas matplotlib networkx

# 6. Install dev dependencies
uv add --dev pytest black ruff ipython jupyter

# 7. Install OSMnx (for real map support)
uv add osmnx geopandas

# 8. Install package in editable mode
uv pip install -e .

pyproject.toml for VRP Toolkit

[project]
name = "vrp-toolkit"
version = "0.1.0"
description = "Reusable VRP/PDPTW solving framework"
requires-python = ">=3.8"
dependencies = [
    "numpy>=1.24.0",
    "pandas>=2.0.0",
    "matplotlib>=3.7.0",
    "networkx>=3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "ipython>=8.0.0",
    "jupyter>=1.0.0",
]
osmnx = [
    "osmnx>=1.6.0",
    "geopandas>=0.14.0",
    "folium>=0.15.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 100
target-version = "py38"

[tool.black]
line-length = 100
target-version = ["py38"]

Install All Dependencies

# Install main dependencies
uv add numpy pandas matplotlib networkx

# Install dev tools
uv add --dev pytest black ruff ipython jupyter

# Install OSMnx group
uv add osmnx geopandas folium

# Or install from pyproject.toml
uv sync

Common Workflows

Daily Development

# Activate environment
source .venv/bin/activate

# Run tests
uv run pytest

# Format code
uv run black .

# Lint code
uv run ruff check .

# Run Jupyter
uv run jupyter lab

Add New Dependency

# Add package
uv add package-name

# Test it works
uv run python -c "import package_name; print('OK')"

# Commit updated pyproject.toml
git add pyproject.toml uv.lock
git commit -m "chore: add package-name dependency"

Clean Install

# Remove existing environment
rm -rf .venv

# Recreate
uv venv

# Reinstall all dependencies
uv sync

# Verify
uv run python -c "import numpy; print(numpy.__version__)"

Comparison with pip/venv

| Task | Traditional | UV | |------|------------|-----| | Create venv | python -m venv .venv | uv venv | | Activate | source .venv/bin/activate | Same | | Install package | pip install package | uv add package | | Install requirements | pip install -r requirements.txt | uv pip install -r requirements.txt | | Freeze deps | pip freeze > requirements.txt | uv pip freeze > requirements.txt | | Run tool | python -m pytest | uv run pytest |

Key Advantages of UV:

  • ⚡ 10-100x faster than pip
  • 🔒 Built-in dependency locking
  • 🐍 Python version management
  • 📦 Cleaner dependency specification in pyproject.toml

Additional Resources

Troubleshooting

Common issues and solutions: See troubleshooting.md

  • UV not found after install
  • Wrong Python version
  • Dependency conflicts
  • Package not found

Advanced Usage

Power user features: See advanced.md

  • Multiple environments
  • Dependency groups
  • Build and publish
  • Integration with other skills

Migration from pip

Convert existing projects: See migration.md

  • Convert requirements.txt to pyproject.toml
  • Migrate existing project step-by-step
  • pip vs UV comparison

Quick Reference

| Task | Command | |------|---------| | Init project | uv init | | Create venv | uv venv | | Add package | uv add package | | Add dev dep | uv add --dev tool | | Install all | uv sync | | Run script | uv run python script.py | | Run tool | uv run pytest | | Update all | uv sync --upgrade | | Lock deps | uv lock | | Export reqs | uv pip freeze > requirements.txt | | Python version | uv python install 3.11 | | Pin Python | uv python pin 3.11 |