Skill: Use uv to manage Python environments

Scope

1. •Create a virtual environment
2. •Install dependencies
3. •Run Python scripts/commands

Assume uv is already available on PATH.

Workflow selection

• •If pyproject.toml exists: use project workflow (uv sync, uv run)
• •Else if requirements.txt exists: use pip workflow (uv venv, uv pip install -r ..., .venv/bin/python ...)
• •Else: stop with an error ("No pyproject.toml or requirements.txt found.")

Project workflow (pyproject.toml)

Create venv + install dependencies

From the repo root (where pyproject.toml is):

• •uv sync

Notes:

• •uv maintains a persistent project environment at .venv and installs deps there.

Run scripts / commands (preferred)

Always run within the project environment:

• •uv run -- python <script.py> [args...]
• •uv run -- python -m <module> [args...]

Notes:

• •uv run executes inside the project environment and ensures it is up-to-date.

Pip workflow (requirements.txt)

Create venv

From the repo root:

• •uv venv # creates .venv by default

Install dependencies

• •uv pip install -r requirements.txt

Run scripts / commands

Run using the venv interpreter directly (no activation required):

• •.venv/bin/python <script.py> [args...]
• •.venv/bin/python -m <module> [args...]

(uv will also automatically find and use the default .venv in subsequent invocations when you use uv pip ... commands.)

Minimal sanity checks (optional)

• •test -x .venv/bin/python
• •uv pip list (verify packages installed)