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)