AgentSkillsCN

uv-python

当您使用 `uv` Python 包管理器来创建/管理虚拟环境、安装或同步依赖项、编译需求文件，或排查 Python 依赖问题时，可选用此方法。当用户提到 `uv`、`uv pip`、`uv venv`、`uv run`、`pyproject.toml`、`uv.lock`、`requirements.in`、`requirements.txt`、依赖锁定/同步，或希望将 pip/venv 工作流迁移到 uv 时，可选用此方法。

SKILL.md
--- frontmatter
name: uv-python
description: Use when working with the `uv` Python package manager to create/manage virtual environments, install or sync dependencies, compile requirements, and troubleshoot Python dependency issues. Trigger for requests mentioning `uv`, `uv pip`, `uv venv`, `uv run`, `pyproject.toml`, `uv.lock`, `requirements.in`, `requirements.txt`, dependency locking/syncing, or migrating from pip/venv workflows to uv.

uv (Python package manager)

Overview

Use uv as the primary interface for Python environments and dependency management. Prefer deterministic installs (lock/sync) and verify exact subcommands/flags with uv --help / uv pip --help when in doubt.

Repo Triage (Do First)

  1. •Identify the dependency source of truth:
  • •pyproject.toml present: project metadata is likely in pyproject.toml.
  • •requirements.in / requirements.txt present: requirements-based workflow.
  1. •Identify reproducibility artifacts:
  • •Lockfile present (ex: uv.lock or a pinned requirements.txt): prefer syncing from it.
  • •No lockfile: compile/generate one before syncing for CI/repro.
  1. •Identify the Python version expectation:
  • •Look for .python-version, pyproject.toml Python constraints, runtime.txt, or CI config.
  • •When creating a venv, explicitly choose a Python if the project requires it.

Core Workflows

1) Create/Repair a Virtual Environment

  1. •If there is already a project venv convention (commonly .venv/), keep it.
  2. •Prefer uv for creation:
  • •uv venv (optionally --python X.Y to match project constraints)
  1. •When troubleshooting, verify which interpreter and site-packages are active before changing deps.

2) Install/Synchronize Dependencies (Requirements-Based)

Use this when the repo is driven by requirements*.txt (or you need pip-compatible behavior).

  1. •If you have requirements.in (unpinned), compile to a pinned file:
  • •Prefer uv pip compile requirements.in -o requirements.txt (or a pinned output like requirements.lock).
  1. •Sync the environment to exactly the pinned requirements:
  • •Prefer uv pip sync requirements.txt for deterministic installs.
  1. •If the user wants a quick, non-deterministic install:
  • •Use uv pip install -r requirements.txt (but call out that it may drift over time).

3) Update Dependencies (Requirements-Based)

  1. •Edit inputs (requirements.in, constraints files, etc.).
  2. •Re-compile pinned requirements.
  3. •Re-sync the environment.
  4. •If tests fail after an update, bisect by reverting the last dependency change or pinning a problematic transitive dependency.

4) Run Tools/Commands Under uv

When a user wants “run tests/lint/build but ensure deps are correct”, prefer uv-managed execution (ex: uv run ... if available in the installed uv) or run commands after a uv pip sync ... to avoid ambient/global Python contamination.

Troubleshooting Checklist

  1. •Confirm you are in the intended environment (venv active, correct Python version).
  2. •Inspect dependency state:
  • •Use uv pip freeze (or pip-equivalent) and compare with the pinned requirements/lock.
  1. •Prefer sync to “make it match” instead of incremental installs.
  2. •If resolution/build fails:
  • •Capture the exact error, platform, Python version, and the command invoked.
  • •Try upgrading build tooling only if needed (and keep changes minimal).

Reference

For command patterns, see references/uv.md.