manage-python-env

Install UV

```bash

# macOS/Linux

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

# Or with pip

pip install uv

# Verify installation

uv --version

```

Create New Project

```bash

# 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

```

Create Virtual Environment

```bash

# 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

```bash

# 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

```

Install Packages

```bash

# 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)

```bash

# 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

```bash

# Remove package

uv remove package-name

# Remove dev dependency

uv remove --dev pytest

```

Update Packages

```bash

# Update single package

uv pip install --upgrade package-name

# Update all packages

uv pip install --upgrade -r requirements.txt

# Sync dependencies (recommended)

uv sync

```

Lock Dependencies

```bash

# Generate lock file

uv lock

# Lock and sync

uv lock --sync

```

Export Requirements

```bash

# Export to requirements.txt

uv pip freeze > requirements.txt

# Export from pyproject.toml

uv export --format requirements-txt > requirements.txt

```

Run Python

```bash

# 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

```bash

# Run pytest

uv run pytest

# Run black

uv run black .

# Run ruff

uv run ruff check .

# Run any tool

uv run tool-name [args]

```

Initial Project Setup

```bash

# 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

```toml

[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

```bash

# 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

```

Daily Development

```bash

# 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

```bash

# 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

```bash

# Remove existing environment

rm -rf .venv

# Recreate

uv venv

# Reinstall all dependencies

uv sync

# Verify

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

```

| 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

Troubleshooting

Common issues and solutions: See [troubleshooting.md](references/troubleshooting.md)

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

Advanced Usage

Power user features: See [advanced.md](references/advanced.md)

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

Migration from pip

Convert existing projects: See [migration.md](references/migration.md)

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

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