agentleFS
Bbar0n234Bbar0n234/learnflow-ai/.claude/skills/uv-package-manager/SKILL.md

uv-package-manager

Skill35 starsChanged 3 months agoApache-2.0View on GitHub

Управление Python-зависимостями через UV package manager. Используй когда: uv, uv sync, uv add, uv run, uv lock, uv pip, pyproject.toml, dependency-groups, optional-dependencies, workspace, монорепозиторий, monorepo, requirements.txt, pip compile, виртуальное окружение Python, venv, установка пакетов.

  • Installs packages

22 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use results-report, python-code-style and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Galaxy-DawnSkill

    results-report

    This skill should be used when the user asks to "write an experiment report", "summarize experimental results", "do experiment retrospection", "write a results report", "写实验总结报告", "写实验复盘", or mentions turning completed experiment artifacts into a structured, decision-oriented research report. It assumes strict analysis should come from `results-analysis` first.

    Also in 3 projects that use this

  • Aver005Skill

    python-code-style

    Python code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.

    Also in 5 projects that use this

  • Clay-HHKSkill

    daily-coding

    Daily coding assistant that auto-triggers when writing/modifying code, providing a core checklist.

    Also in 3 projects that use this

  • Clay-HHKSkill

    kaggle-learner

    This skill should be used when the user asks to "learn from Kaggle", "study Kaggle solutions", "analyze Kaggle competitions", or mentions Kaggle competition URLs. Provides access to extracted knowledge from winning Kaggle solutions across NLP, CV, time series, tabular, and multimodal domains.

    Also in 3 projects that use this

  • CodeWithBehnamSkill

    python-type-safety

    Python type safety with type hints, generics, protocols, and strict type checking. Use when adding type annotations, implementing generic classes, defining structural interfaces, or configuring mypy/pyright.

    Also in 4 projects that use this

  • CodeWithBehnamSkill

    python-observability

    Python observability patterns including structured logging, metrics, and distributed tracing. Use when adding logging, implementing metrics collection, setting up tracing, or debugging production systems.

    Also in 3 projects that use this

  • +2 more from Clay-HHK

The file

Files
SKILL.md

UV Package Manager

Обзор

UV — современный package manager для Python от Astral (авторы Ruff). Замена pip, pip-tools, poetry, pipenv. Написан на Rust, работает в 10-100x быстрее pip.

Ключевые концепции:

  • pyproject.toml — источник истины для зависимостей
  • uv.lock — lock-файл с точными версиями (рекомендуется вместо requirements.txt)
  • .venv — виртуальное окружение (создаётся автоматически)

Базовые команды

Инициализация проекта

# Новый проект
uv init myproject
cd myproject

# Инициализация в существующей директории
uv init

# Создать как библиотеку (с src/ layout)
uv init --lib

# Создать пакет в workspace
uv init --package packages/mylib

Управление зависимостями

# Добавить зависимость
uv add fastapi
uv add "httpx>=0.25"

# Добавить dev-зависимость (в группу dev)
uv add --dev pytest ruff mypy

# Добавить в произвольную группу
uv add --group docs sphinx mkdocs

# Добавить в optional-dependencies (для пользователей пакета)
uv add --optional postgres asyncpg

# Удалить зависимость
uv remove httpx

# Обновить зависимость
uv lock --upgrade-package fastapi

Синхронизация окружения

# Синхронизировать все зависимости (создаёт .venv если нет)
uv sync

# Без dev-зависимостей
uv sync --no-dev

# С конкретной группой
uv sync --group docs

# Все группы
uv sync --all-groups

# Только указанная группа (без проекта)
uv sync --only-group test

# Для workspace — все пакеты
uv sync --all-packages

# Для workspace — конкретный пакет
uv sync --package backend

Запуск команд

# Запуск в виртуальном окружении
uv run python script.py
uv run pytest
uv run ruff check .

# Запуск для конкретного пакета в workspace
uv run --package backend uvicorn app:main --reload

# Без dev-зависимостей
uv run --no-dev python script.py

Lock-файл

# Обновить lock-файл
uv lock

# Обновить все зависимости
uv lock --upgrade

# Обновить конкретный пакет
uv lock --upgrade-package requests

# Проверить что lock актуален
uv lock --check

Dependency Groups (PEP 735)

Когда что использовать

ТипПубликуется в PyPIНазначение
[project.dependencies]ДаОсновные зависимости пакета
[project.optional-dependencies]ДаОпциональные фичи для пользователей
[dependency-groups]НетDev-инструменты (test, lint, docs)

Синтаксис в pyproject.toml

[project]
dependencies = [
    "fastapi>=0.100",
    "pydantic>=2.0",
]

# Для пользователей пакета (pip install mypackage[postgres])
[project.optional-dependencies]
postgres = ["asyncpg>=0.29"]
redis = ["redis>=5.0"]

# Только для разработки (не публикуется)
[dependency-groups]
test = [
    "pytest>=8.0",
    "pytest-cov",
    "pytest-asyncio",
]
lint = [
    "ruff>=0.4",
    "mypy>=1.10",
]
docs = [
    "sphinx>=7.0",
    "mkdocs",
]
# Композиция групп
dev = [
    {include-group = "test"},
    {include-group = "lint"},
    "ipython",
]

Команды для групп

# Добавление
uv add --dev pytest          # В группу dev
uv add --group lint ruff     # В группу lint
uv add --optional api httpx  # В optional-dependencies.api

# Синхронизация
uv sync                      # dev по умолчанию
uv sync --group docs         # + docs
uv sync --all-groups         # Все группы
uv sync --only-group test    # Только test
uv sync --no-dev             # Без dev

Настройка default-groups

[tool.uv]
default-groups = ["dev"]  # Синхронизируются по умолчанию

Workspaces (Монорепозитории)

Конфигурация

Корневой pyproject.toml:

[project]
name = "my-monorepo"
version = "0.1.0"
requires-python = ">=3.12"

[tool.uv.workspace]
members = [
    "backend",
    "bot",
    "packages/*",
]
exclude = ["packages/deprecated"]

[dependency-groups]
dev = []
experiments = ["jupyterlab", "pandas"]

Пакет в workspace:

# backend/pyproject.toml
[project]
name = "backend"
version = "0.1.0"
dependencies = [
    "shared-lib",      # Зависимость от другого workspace member
    "fastapi>=0.100",
]

# ВАЖНО: указать что shared-lib из workspace
[tool.uv.sources]
shared-lib = { workspace = true }

[dependency-groups]
dev = ["pytest", "ruff", "mypy"]

Команды для workspace

# Синхронизация всех пакетов
uv sync --all-packages

# Конкретный пакет
uv sync --package backend

# Запуск для конкретного пакета
uv run --package backend uvicorn app:main --reload
uv run --package bot python -m bot.main

# Сборка конкретного пакета
uv build --package backend

# Добавление зависимости в конкретный пакет
uv add --package backend httpx

Типичная структура

my-monorepo/
├── pyproject.toml          # Workspace config
├── uv.lock                  # Единый lock-файл
├── .python-version
│
├── packages/
│   ├── core/
│   │   ├── pyproject.toml
│   │   └── src/core/
│   └── utils/
│       ├── pyproject.toml
│       └── src/utils/
│
├── services/
│   ├── backend/
│   │   ├── pyproject.toml
│   │   └── src/backend/
│   └── worker/
│       ├── pyproject.toml
│       └── src/worker/
│
└── Makefile

Docker для workspace

FROM python:3.13-slim

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Сначала только файлы конфигурации (кэширование)
COPY pyproject.toml uv.lock ./
COPY backend/pyproject.toml backend/

# Установить зависимости без проекта
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --package backend --no-install-project --frozen

# Затем код
COPY backend/src backend/src

# Установить проект
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --package backend --frozen

CMD ["uv", "run", "--package", "backend", "uvicorn", "backend.main:app"]

Работа с requirements.txt

Когда использовать

  • uv.lock — рекомендуется для всех проектов с UV
  • requirements.txt — совместимость с системами без UV (CI, Docker)

Генерация из pyproject.toml

# uv pip compile (pip-tools стиль)
uv pip compile pyproject.toml -o requirements.txt

# С extras
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

# С группами
uv pip compile pyproject.toml --group test -o requirements-test.txt

# С хешами (безопасность)
uv pip compile pyproject.toml --generate-hashes -o requirements.txt

# Кросс-платформенный
uv pip compile pyproject.toml --universal -o requirements.txt

Экспорт из uv.lock

# Экспорт в requirements.txt
uv export --format requirements.txt -o requirements.txt

# Без dev
uv export --format requirements.txt --no-dev -o requirements.txt

# Для конкретного пакета workspace
uv export --format requirements.txt --package backend -o requirements.txt

Установка из requirements.txt

# Установить (не удаляет лишние)
uv pip install -r requirements.txt

# Синхронизировать (удаляет лишние)
uv pip sync requirements.txt

pip-совместимый интерфейс

# Полный pip-совместимый интерфейс
uv pip install fastapi
uv pip install -e .
uv pip freeze > requirements.txt
uv pip list
uv pip show fastapi
uv pip uninstall fastapi

Типичные Makefile команды

.PHONY: install lint format typecheck test run-backend

install:  ## Установить все зависимости
	uv sync --all-packages

lint:  ## Проверить код
	uv run ruff check .

lint-fix:  ## Автоисправление
	uv run ruff check . --fix

format:  ## Форматирование
	uv run ruff format .

typecheck:  ## Проверка типов
	uv run mypy backend bot

test:  ## Запуск тестов
	uv run pytest -v

run-backend:  ## Запуск backend
	uv run --package backend uvicorn backend.main:app --reload

run-bot:  ## Запуск bot
	uv run --package bot python -m bot.main

# Комплексная проверка
check: format lint typecheck test
	@echo "All checks passed!"

Полезные команды

# Информация о пакете
uv pip show fastapi

# Дерево зависимостей
uv tree
uv tree --package backend

# Очистка кэша
uv cache clean

# Python версии
uv python list
uv python install 3.13
uv python pin 3.13

# Создать venv явно
uv venv
uv venv --python 3.13

# Информация о проекте
uv version

Troubleshooting

Lock-файл устарел

# Ошибка: "Resolved requirements are not up to date"
uv lock
uv sync

Конфликт версий

# Посмотреть почему конфликт
uv lock -v

# Принудительно обновить
uv lock --upgrade

Проблемы с кэшем

uv cache clean
uv sync --refresh

Workspace пакет не находится

# Убедиться что в обоих местах:
# 1. В dependencies
dependencies = ["shared-lib"]

# 2. В sources
[tool.uv.sources]
shared-lib = { workspace = true }

Debug режим

uv sync -v      # Verbose
uv sync -vv     # Very verbose
UV_LOG=debug uv sync

Миграция

С pip на UV

# Импорт из requirements.txt
uv add -r requirements.txt

# С сохранением версий
uv add -r requirements.txt -c requirements.txt

С Poetry на UV

# UV понимает poetry.lock
uv sync  # Автоматически конвертирует

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.