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)