Как перевести Python-проект на uv и Ruff в 2026 году

Команды миграции с pip и Flake8, настройка CI, замер скорости и риски инструментов Astral.

Обложка: Как перевести Python-проект на uv и Ruff в 2026 году

uv и Ruff — два инструмента компании Astral, написанные на Rust. Первый берёт на себя работу pip, pip-tools, pipx, poetry, pyenv, twine и virtualenv, второй заменяет Flake8 с плагинами, Black, isort, pydocstyle, pyupgrade и autoflake. По данным PyPI Stats на 16 ноября 2026 года, за последний месяц Ruff скачали 408 млн раз, а uv набрал 180 млн загрузок. Это больше, чем у Black (113 млн), poetry (43 млн) и Flake8 (41 млн).

Перейти проще, чем кажется: uv умеет работать как прямая замена pip install, а существующие requirements.txt переносятся в pyproject.toml и общий lock-файл одной командой с сохранением зафиксированных версий. Ruff читает настройки из того же pyproject.toml и повторяет правила Flake8 и стиль Black.

Ниже — пошаговый план перехода: установка, перенос зависимостей, настройка линтера и форматтера, CI и pre-commit. Также разберём замеры скорости и риски привязки к инструментам с версиями 0.x. Команды и конфигурация взяты из документации uv 0.13.8 и Ruff 0.17.5; обе версии вышли 12 ноября 2026 года.

Ключевые выводы
  • uv заменяет pip, pip-tools, pipx, poetry, pyenv, twine и virtualenv; Ruff — Flake8, Black, isort, pydocstyle, pyupgrade и autoflake.
  • В нашем замере на Linux установка 79 пакетов из тёплого кэша заняла 21,7 с у pip 26.3 и 0,19 с у uv 0.13.8.
  • Команда uv add -r requirements.in -c requirements.txt переносит зависимости в pyproject.toml и uv.lock, не меняя зафиксированные версии.
  • Ruff 0.16 в июле 2026 года расширил набор правил по умолчанию с 59 до 413: после обновления со старой версии линтер найдёт больше замечаний.
  • Ruff распространяется по лицензии MIT, uv — по Apache 2.0 или MIT на выбор; в марте 2026 года Astral объявила о переходе в OpenAI, в команду Codex.
  • uv не читает pip.conf и PIP_INDEX_URL: адрес зеркала PyPI придётся прописать заново.

Что такое uv и Ruff и какие инструменты они заменяют?

uv — менеджер пакетов и проектов для Python, а Ruff служит линтером и форматтером кода. Оба распространяются готовыми бинарными файлами, компилятор Rust для установки не нужен. В документации uv интерфейс разбит на независимые части: версии Python, скрипты, проекты, утилиты командной строки и режим совместимости с pip.

Что на что меняется при переходе

9 сервисов, 3 столбца
Что на что меняется при переходе
ЗадачаБылоСтало
Установка пакетовpip installuv pip install или uv add
Виртуальное окружениеpython -m venv, virtualenvuv venv, в проектах создаётся само
Фиксация версийpip-compile из pip-tools, poetry.lockuv lock, uv pip compile
Версии Pythonpyenvuv python install
Утилиты командной строкиpipxuvx, uv tool install
Сборка и публикацияbuild, twineuv build, uv publish
ЛинтерFlake8 с плагинами, pyupgrade, autoflakeruff check
ФорматированиеBlackruff format
Сортировка импортовisortruff check --select I --fix
Листайте столбцы →Смахните влевоВсе 3 столбца
документация uv и Ruff, 16 ноября 2026 года

Исходный код обоих инструментов открыт. Ruff распространяется по лицензии MIT, uv — по Apache 2.0 или MIT на выбор пользователя. На 16 ноября 2026 года у uv 92 тыс. звёзд на GitHub, у Ruff 51 тыс. Судя по README проекта, Ruff используют Apache Airflow, FastAPI, pandas, SciPy и библиотека transformers от Hugging Face.

Как перевести Python-проект на uv и Ruff в 2026 году_8
Загрузки пакетов с PyPI за последний месяц на 16 ноября 2026 года, млн. График: Tproger по данным PyPI Stats

Это общее число скачиваний с PyPI: в него входят и установки в CI, поэтому с числом разработчиков цифры не совпадают. Сам pip в сравнение не включён: он поставляется вместе с Python.

Насколько uv и Ruff быстрее pip, Flake8 и Black?

Astral заявляет ускорение от 10 до 100 раз для обоих инструментов, но цифра зависит от сценария. Замеры uv компания делала на macOS с Python 3.12.4 на зависимостях документации библиотеки Trio и сама оговаривает ограничения: результат сильно зависит от операционной системы и файловой системы (на macOS uv использует reflink, на Linux — жёсткие ссылки), а если в наборе есть пакет, который долго собирается из исходников, разница между менеджерами почти исчезает.

Как перевести Python-проект на uv и Ruff в 2026 году_12
Установка зависимостей Trio из тёплого кэша, секунды, меньше — лучше. Источник: Astral

Мы повторили сценарий с тёплым кэшем на Linux (AMD Ryzen 9 5900X, Python 3.13.3): в пустое виртуальное окружение ставили 79 пакетов с зафиксированными версиями — FastAPI с набором standard, SQLAlchemy, pandas, pytest, httpx, Celery и их зависимости. Перед каждым прогоном окружение создавалось заново, затем выполнялась команда pip install -r или uv pip install -r с одним и тем же списком версий и заполненным кэшем. Медиана 5 прогонов: 21,7 с у pip 26.3 (от 18,1 до 22,1 с) и 0,19 с у uv 0.13.8 (от 0,19 до 0,23 с), разница примерно в 110 раз. С холодным кэшем время у обоих определяет скорость сети: первая установка с пустым кэшем заняла 253 с у pip и 223 с у uv, почти всё это время ушло на скачивание пакетов по медленному каналу. Разница при тёплом кэше во многом объясняется тем же: pip и с заполненным кэшем обращается к индексу (при недоступной сети установка у нас завершилась ошибкой), а uv поставил те же пакеты с флагом --offline.

Как перевести Python-проект на uv и Ruff в 2026 году_14
Установка 79 пакетов в пустое окружение из тёплого кэша, секунды, медиана 5 прогонов. График: замер Tproger, 16 ноября 2026 года

Для Ruff в README приведён замер на исходниках CPython без кэша: Ruff проверил их за 0,29 с, Autoflake за 6,18 с, Flake8 за 12,26 с, Pyflakes за 15,79 с, Pycodestyle за 46,92 с, Pylint не уложился в 60 с. Железо и версии инструментов рядом с графиком не указаны, так что это ориентир от вендора. Независимые оценки приводятся там же, в отзывах разработчиков.

Как перевести Python-проект на uv и Ruff в 2026 году_16
Проверка исходного кода CPython без кэша, секунды; для Pylint показана нижняя граница 60 с. График: Tproger по данным README Ruff, замер Astral
Why is Ruff a gamechanger? Primarily because it is nearly 1000x faster. Literally. Not a typo. On our largest module (dagster itself, 250k LOC) pylint takes about 2.5 minutes, parallelized across 4 cores on my M1. Running ruff against our entire codebase takes .4 seconds.
Ник Шрокоснователь Elementl, соавтор GraphQL (перевод: «Почему Ruff меняет правила игры? Прежде всего потому, что он почти в 1000 раз быстрее. Буквально, это не опечатка. На нашем самом большом модуле, самом dagster на 250 тыс. строк, pylint работает около 2,5 минуты на 4 ядрах моего M1. Проверка всей нашей кодовой базы через ruff занимает 0,4 секунды»)
Ruff is ~150-200x faster than flake8 on my machine, scanning the whole repo takes ~0.2s instead of ~20s. This is an enormous quality of life improvement for local dev. It's fast enough that I added it as an actual commit hook, which is terrific.
Брайан Ван де Венсоавтор Bokeh, автор первой версии Conda (перевод: «На моей машине Ruff примерно в 150–200 раз быстрее flake8: проверка всего репозитория занимает около 0,2 с вместо 20 с. Это огромное улучшение для локальной разработки. Он достаточно быстр, чтобы я поставил его прямо в хук на коммит, и это прекрасно»)

Практический смысл скорости в том, что проверки переезжают из CI ближе к редактору. Линтер, который отрабатывает за доли секунды, можно запускать при каждом сохранении файла и в хуке на коммит, а окружение из кэша пересоздаётся быстрее, чем разработчик успевает переключить окно.

Как установить uv и перенести проект с requirements.txt?

uv ставится одной командой, Python для этого не нужен. В инструкции по установке основным способом назван отдельный установщик; есть пакеты в PyPI, Homebrew, WinGet, Scoop и образ Docker.

			# macOS и Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# конкретная версия
curl -LsSf https://astral.sh/uv/0.13.8/install.sh | sh

# альтернативы
pipx install uv
brew install uv
winget install --id=astral-sh.uv -e
		

Версия, установленная этим установщиком, обновляется командой uv self update. Нужный интерпретатор uv скачает сам: uv python install 3.12 ставит сборку из проекта python-build-standalone, который ведёт Astral, а если подходящий Python уже есть в системе, uv найдёт его без настройки.

Самый осторожный вариант перехода — оставить структуру проекта как есть и заменить только команды: uv venv создаёт окружение .venv, uv pip install -r requirements.txt ставит в него пакеты. Полный переход описан в руководстве по миграции с pip: зависимости переезжают в pyproject.toml, а точные версии фиксируются в uv.lock.

			# создать pyproject.toml, если его ещё нет
uv init

# перенести зависимости, сохранив уже зафиксированные версии
uv add -r requirements.in -c requirements.txt

# зависимости для разработки уходят в отдельную группу
uv add --dev -r requirements-dev.in -c requirements-dev.txt

# запуск в окружении проекта
uv run pytest
		

Флаг -c передаёт старый requirements.txt как ограничения, поэтому при переносе версии не меняются. Если requirements-dev.in подключает основной файл строкой -r requirements.in, её нужно убрать перед импортом, иначе основные зависимости попадут и в группу dev; в руководстве для этого приведён вариант с sed. Если файла requirements.in в проекте нет и зависимости велись через pip freeze, прямые зависимости придётся выписать руками. После переноса стоит учитывать такие особенности:

  • uv.lock универсален: один файл описывает зависимости для всех платформ и всех групп, отдельные requirements-win.txt и requirements-dev.txt больше не нужны. Файл коммитят в репозиторий и не редактируют руками.
  • uv run перед каждым запуском проверяет, что lock-файл соответствует pyproject.toml, а окружение — lock-файлу, и при расхождении синхронизирует их.
  • В проекте uv использует окружение .venv в корне и игнорирует активированное через VIRTUAL_ENV; поведение меняет флаг --active.
  • Версия Python закрепляется в файле .python-version, его создаёт uv init.

Список отличий от pip собран на отдельной странице, и несколько особенностей чаще всего ломают привычные сценарии. uv не читает pip.conf и переменные вроде PIP_INDEX_URL. Он ставит пакеты только в виртуальное окружение, для системного интерпретатора нужен флаг --system или явный путь через --python. Наконец, при нескольких индексах uv берёт версии пакета только из первого индекса, где пакет нашёлся: так он защищает от подмены внутреннего пакета одноимённым с PyPI.

Команде с внутренним зеркалом PyPI адрес нужно перенести в настройки uv. Индекс объявляется в pyproject.toml; запись с default = true заменяет PyPI, говорится в разделе об индексах. То же делает переменная окружения UV_DEFAULT_INDEX.

			[[tool.uv.index]]
name = "mirror"
url = "https://pypi.example.org/simple"
default = true
		

Ещё одна возможность, ради которой uv ставят даже без переноса проекта, — скрипты со встроенными зависимостями. Команда uv add --script дописывает в начало файла блок метаданных по PEP 723, а uv run example.py создаёт под него временное окружение.

			# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
		

Как заменить Flake8, isort и Black на Ruff?

Ruff добавляется в проект как зависимость для разработки и сразу работает без настройки. Порядок из учебника Ruff: поставить, запустить линтер с автоисправлением, затем форматтер.

			uv add --dev ruff

uv run ruff check          # найти проблемы
uv run ruff check --fix    # исправить то, что исправляется автоматически
uv run ruff format         # отформатировать код

# импорты сортирует линтер, правило I
uv run ruff check --select I --fix
		

Настройки лежат в pyproject.toml, ruff.toml или .ruff.toml. Правила выбираются по префиксам: F (Pyflakes), E и W (pycodestyle), B (flake8-bugbear), UP (pyupgrade), I (isort). Пример из учебника для проекта с Python 3.10 и строкой в 79 знаков:

			[project]
# Support Python 3.10+.
requires-python = ">=3.10"

[tool.ruff]
# Set the maximum line length to 79.
line-length = 79

[tool.ruff.lint]
# Add the `line-too-long` rule to the enforced rule set.
extend-select = ["E501"]
		

О совместимости с другими инструментами подробно сказано в ответах на частые вопросы в документации:

  • Black. Форматтер Ruff задуман как прямая замена: на проектах, уже отформатированных Black, таких как Django и Zulip, совпадает больше 99,9% строк. Длина строки по умолчанию та же, 88 знаков.
  • Flake8. Ruff заменяет его напрямую, если плагинов нет или их немного, рядом используется форматтер и код написан на Python 3. Встроены аналоги десятков плагинов, среди них flake8-bugbear, flake8-comprehensions, flake8-simplify, pep8-naming и mccabe.
  • isort. Сортировка импортов близка к профилю black в isort.
  • Pylint. Полной замены нет: из примерно 409 правил Pylint с Ruff пересекаются не меньше 209, а проверок, требующих вывода типов, в Ruff меньше.
  • Проверка типов. Ruff её не делает; документация советует держать рядом ty, mypy или Pyright.
  • Свои плагины. Сторонние плагины Ruff пока не поддерживает, так что самописные правила для Flake8 перенести не получится.

Главная ловушка при обновлении — набор правил по умолчанию. В Ruff 0.16, вышедшем 23 июля 2026 года, он вырос с 59 до 413 правил из 968: добавились проверки из flake8-bugbear, pyupgrade и собственной категории RUF, а 18 правил pycodestyle и Pyflakes из набора убрали. Проект, который обновляется с версии 0.15 или более ранней без явного select, получит новые замечания. Вернуть прежний набор можно одной строкой:

			[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]
		
Ruff is so fast that sometimes I add an intentional bug in the code just to confirm it's actually running and checking the code.
Себастьян Рамирессоздатель FastAPI (перевод: «Ruff настолько быстрый, что иногда я специально добавляю в код ошибку, чтобы убедиться, что он действительно запускается и проверяет код»)

Как подключить uv и Ruff в CI и pre-commit?

В CI достаточно поставить uv, синхронизировать окружение по lock-файлу и запускать всё через uv run. Для GitHub Actions Astral ведёт действие astral-sh/setup-uv; в руководстве советуют закреплять и версию действия, и версию uv.

			name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.13.8"
          enable-cache: true
      - name: Install the project
        run: uv sync --locked --all-extras --dev
      - name: Run Ruff
        run: uv run ruff check --output-format=github .
      - name: Run tests
        run: uv run pytest tests
		

Флаг --locked останавливает сборку, если uv.lock отстал от pyproject.toml: так в основную ветку не попадёт несинхронизированный lock-файл. Для GitLab CI в документации Ruff есть готовый пример с образом ghcr.io/astral-sh/ruff:0.17.5-alpine и отчётом в формате Code Quality через --output-format=gitlab; как сократить сам пайплайн, мы разбирали в материале про семь приёмов GitLab CI. В Dockerfile uv проще всего взять из официального образа: COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/.

Локально те же проверки запускает pre-commit. Хуки лежат в репозитории astral-sh/ruff-pre-commit:

			- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.17.5
  hooks:
    # Run the linter.
    - id: ruff-check
      args: [ --fix ]
    # Run the formatter.
    - id: ruff-format
		

Чем рискует команда, которая переходит на инструменты Astral?

Основные риски связаны с версиями 0.x, сменой владельца и функциями в статусе preview. По первому пункту у uv есть письменные обязательства. В политике версионирования он назван стабильным продуктом для продакшена; ломающие изменения выходят только со сменой минорной версии, и только с ней может поменяться схема uv.lock. Вывод для практики: закреплять версию uv в CI и обновлять минорные версии осознанно. К Ruff это относится в той же мере, что показала история с правилами по умолчанию в 0.16.

Второй риск появился 19 марта 2026 года, когда основатель Astral Чарли Марш объявил о соглашении, по которому компания переходит в OpenAI, в команду Codex. Мы писали об этом в обзоре новостей Python за апрель. В анонсе обещано, что инструменты останутся открытыми.

In line with our philosophy and OpenAI's own announcement, OpenAI will continue supporting our open source tools after the deal closes. We'll keep building in the open, alongside our community – and for the broader Python ecosystem – just as we have from the start.
Чарли Маршоснователь Astral (перевод: «В соответствии с нашей философией и собственным анонсом OpenAI, после закрытия сделки OpenAI продолжит поддерживать наши инструменты с открытым кодом. Мы и дальше будем разрабатывать их открыто, вместе с сообществом и для всей экосистемы Python, как делали с самого начала»)

Обещание компании не равно гарантии, но лицензии MIT и Apache 2.0 разрешают форк: если приоритеты владельца изменятся, сообщество сможет продолжить разработку от последней открытой версии. Это наша оценка, в анонсе о таком сценарии ничего нет. После объявления релизы выходят в прежнем темпе: у uv вышло 3 версии с 27 октября по 12 ноября 2026 года.

Третий риск — новые функции, которые легко принять за готовые. Проверка зависимостей на уязвимости uv audit и поиск известных вредоносных пакетов при установке (UV_MALWARE_CHECK=1) вышли в июне 2026 года в статусе preview, и Astral предупреждает о возможных ломающих изменениях. Общая команда uv check, которая готовит окружение и запускает проверку типов через ty, появилась в октябре как экспериментальная; сам ty пока выходит в версиях 0.0.x. В основу процесса такие команды ставить рано, а про проверку зависимостей другими средствами у нас есть отдельный разбор.

Кому переход почти ничего не даст: проекту, где линтинг держится на самописных плагинах Flake8 или на проверках Pylint с выводом типов. Остальным имеет смысл начать с малого: поставить uv рядом с pip, прогнать uvx ruff check на своём репозитории и посмотреть на результат до любых изменений в проекте.

Частые вопросы
1
Можно ли пользоваться uv как быстрым pip и не заводить pyproject.toml?

Да. Команды uv venv, uv pip install, uv pip compile и uv pip sync повторяют сценарии venv, pip и pip-tools и работают с обычными requirements.txt. Документация называет этот режим интерфейсом для существующих процессов и предупреждает, что полного совпадения с pip нет.

2
Нужно ли хранить uv.lock в репозитории?

Да. Документация uv прямо советует добавлять файл в систему контроля версий: по нему у всех разработчиков и в CI ставятся одни и те же версии. Редактировать его руками не нужно, файл ведёт uv.

3
Какие версии Python поддерживает Ruff?

Ruff проверяет код для Python 3.7 и новее, включая Python 3.15, и сам устанавливается под любую из этих версий. Python 2 не поддерживается.

4
Умеет ли Ruff работать с Jupyter Notebook и Markdown?

Да. Линтер и форматтер поддерживают блокноты Jupyter из коробки, а начиная с версии 0.16 ruff format форматирует блоки кода на Python внутри файлов Markdown.

5
Надо ли устанавливать Rust, чтобы пользоваться uv и Ruff?

Нет. Оба инструмента распространяются готовыми бинарными файлами. Rust понадобится только при сборке из исходников, например через cargo install --locked uv или на платформе, для которой нет готовой сборки.

Источники: Документация uv, uv: Installation, uv: Migrating from pip to a uv project, uv: Compatibility with pip and pip-tools, uv: Package indexes, uv: Using uv in GitHub Actions, uv: Versioning policy, uv: BENCHMARKS.md, Документация Ruff, Ruff: Tutorial, Ruff: FAQ, Ruff: Integrations, GitHub: astral-sh/ruff, README, Astral: Ruff v0.16.0, Astral: Astral to join OpenAI, Astral: Vulnerability and malware checks in uv, Astral: Bringing uv and ty together, PyPI Stats: ruff, PyPI Stats: uv

Изображение на обложке: Astral