Установка Ruff

Ruff — это линтер и форматтер для Python, написанный на Rust. Он работает в десятки раз быстрее традиционных инструментов вроде Flake8, pylint или Black, сохраняя при этом обратную совместимость с существующими экосистемами. Благодаря своей скорости Ruff идеально подходит для использования в больших монорепозиториях, CI-пайплайнах и редакторах кода в реальном времени. В этом уроке мы подробно разберём все возможные способы установки Ruff, чтобы вы могли выбрать наиболее подходящий для вашего рабочего окружения.

Независимо от того, работаете ли вы на Windows, macOS или Linux, используете ли вы классический pip или современные инструменты вроде uv и conda, — установка Ruff занимает буквально несколько секунд. Главное преимущество Ruff в том, что это единственный бинарный файл без внешних зависимостей: вам не нужно устанавливать Python-зависимости для самого линтера. Это означает, что Ruff работает одинаково быстро и стабильно в любом окружении.

Самый простой и распространённый способ установки Ruff — через pip. Ruff распространяется как Python-пакет через PyPI (Python Package Index). Это означает, что установка происходит так же, как и любого другого Python-пакета. Однако важно понимать, что Ruff — это не pure-Python пакет; при установке через pip загружается предварительно собранный бинарный файл (wheel) под вашу платформу. Благодаря этому вам не нужен компилятор Rust на вашей машине.

Рекомендуется устанавливать Ruff в изолированном виртуальном окружении или в качестве dev-зависимости проекта. Избегайте глобальной установки через pip system-wide, так как это может привести к конфликтам версий с другими инструментами.

# Установка через pip
pip install ruff

# Для конкретного пользователя (без sudo)
pip install --user ruff

# В виртуальное окружение
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
pip install ruff

# Как dev-зависимость в проекте (в requirements-dev.txt)
pip install ruff
pip freeze | grep ruff >> requirements-dev.txt

Установка через pip в виртуальное окружение

Настоятельно рекомендуется устанавливать Ruff в виртуальное окружение вашего проекта. Вот полный пошаговый процесс:

# Шаг 1: создать виртуальное окружение
python -m venv .venv

# Шаг 2: активировать его
# На macOS/Linux:
source .venv/bin/activate
# На Windows (cmd):
# .venv\Scripts\activate
# На Windows (PowerShell):
# .venv\Scripts\Activate.ps1

# Шаг 3: установить ruff
pip install ruff

# Шаг 4: проверить установку
ruff --version

# Шаг 5: (опционально) сохранить зависимость
pip freeze | grep ruff

Установка через poetry

Если вы используете Poetry для управления зависимостями, установка Ruff выполняется одной командой:

# Добавить как dev-зависимость
poetry add --group dev ruff

# Или как обычную зависимость
poetry add ruff

# Проверить
poetry run ruff --version

Установка через pdm

# Добавить как dev-зависимость
pdm add --dev ruff

# Запуск через pdm
pdm run ruff --version

Преимущества установки через pip

Установка через pip даёт несколько преимуществ. Во-первых, это универсальный способ, который работает на любой платформе: Windows, macOS и Linux. Во-вторых, вы получаете версию Ruff, совместимую с вашей версией Python и операционной системой, без необходимости компилировать что-либо вручную. В-третьих, pip автоматически управляет зависимостями и версиями, что упрощает обновление и удаление пакета. Однако учтите, что при использовании pip вы получите бинарную сборку, которая может быть немного больше по размеру, чем при установке через Cargo, из-за включения всех необходимых библиотек.

Недостатки установки через pip

Основной недостаток pip — это скорость установки и необходимость в виртуальном окружении. Хотя сам Ruff устанавливается быстро, pip загружает и обрабатывает метаданные пакета, что может занять несколько секунд. Кроме того, если вы забудете активировать виртуальное окружение, Ruff может установиться глобально, что нежелательно. Также pip требует установленного Python на машине, что может быть проблемой для CI-образов, где установлен только Python минимальной конфигурации.

Ещё один нюанс: при использовании pip вы получаете ту версию Ruff, которая опубликована на PyPI. Между выходом новой версии на GitHub и её появлением на PyPI может пройти несколько часов или даже дней. Если вам нужна самая свежая версия Ruff (например, с только что добавленным правилом), используйте установку через Cargo или standalone-скрипт.

uv — это современный менеджер пакетов для Python, написанный на Rust той же командой, что и Ruff (Astral). Он спроектирован как более быстрая альтернатива pip, pip-tools и virtualenv. uv может устанавливать пакеты в 10-100 раз быстрее, чем pip, благодаря эффективному кэшированию, параллельной загрузке и продвинутому разрешению зависимостей. Если вы ещё не знакомы с uv, настоятельно рекомендуем попробовать его — вы будете приятно удивлены скоростью работы.

Использование uv для установки Ruff — это рекомендуемый способ от разработчиков Astral. uv умеет устанавливать инструменты как изолированные исполняемые файлы (через uv tool) и как dev-зависимости проекта (через uv add). Кроме того, uv автоматически выбирает лучшую доступную бинарную сборку для вашей платформы.

Установка uv

Если у вас ещё не установлен uv, его можно установить несколькими способами:

# macOS/Linux — через standalone-скрипт
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows — через PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS — через Homebrew
brew install uv

# Linux — через pip
pip install uv

# Через Cargo
cargo install uv

Установка Ruff через uv (как dev-зависимость проекта)

Самый правильный способ использования Ruff в проекте — добавить его как dev-зависимость. Тогда все участники команды будут использовать одну и ту же версию Ruff, а сам линтер не попадёт в production-окружение:

# Инициализировать проект (если ещё не сделано)
uv init

# Добавить Ruff как dev-зависимость
uv add --dev ruff

# Теперь Ruff установлен и доступен через uv run
uv run ruff --version

# Запуск линтинга
uv run ruff check .

# Запуск форматирования
uv run ruff format .

uv создаст файл pyproject.toml (или обновит существующий), добавив Ruff в секцию [tool.uv.dev-dependencies] или [dependency-groups.dev]. Все команды Ruff следует запускать через uv run ruff, чтобы uv автоматически подставлял правильную версию из проекта. Если вы просто выполните ruff check . в терминале, то запустится глобальная версия Ruff (если она установлена), а не версия из проекта.

Установка Ruff глобально через uv tool

Если вы хотите использовать Ruff как глобальный инструмент (например, для быстрой проверки любых проектов или для использования в редакторе кода), uv предоставляет команду uv tool install. Это аналог pipx, но реализованный средствами uv:

# Установить Ruff глобально
uv tool install ruff

# Теперь команда ruff доступна глобально
ruff --version

# Запуск линтинга
ruff check .

# Запуск форматирования
ruff format .

# Обновление глобальной версии
uv tool upgrade ruff

# Удаление глобальной версии
uv tool uninstall ruff

Команда uv tool install создаёт изолированное виртуальное окружение для каждого инструмента и добавляет символическую ссылку на исполняемый файл в директорию ~/.local/bin (или эквивалентную на вашей платформе). Это гарантирует, что инструмент не будет конфликтовать с зависимостями ваших проектов.

Использование uv с локальным проектом

uv автоматически обнаруживает виртуальное окружение в директории проекта. Если вы создали виртуальное окружение через uv venv и активировали его, то ruff будет вызываться из этого окружения, даже без префикса uv run. Вот пример рабочего процесса:

# Создать виртуальное окружение
uv venv

# Активировать (macOS/Linux)
source .venv/bin/activate

# Установить все зависимости
uv sync

# Теперь ruff доступен напрямую
ruff check .
ruff format .

pipx — это инструмент для установки Python-приложений в изолированные окружения. В отличие от pip, который устанавливает пакеты в текущее виртуальное окружение, pipx создаёт отдельное изолированное окружение для каждого инструмента и делает его исполняемый файл доступным глобально через символическую ссылку в ~/.local/bin. Это идеальный способ установки Ruff, если вы хотите иметь к нему доступ из любого места в системе, но при этом не хотите загрязнять глобальное окружение Python.

pipx особенно полезен, если вы используете несколько версий Ruff для разных проектов или если вы хотите изолировать инструменты друг от друга. Каждый инструмент, установленный через pipx, живёт в собственном виртуальном окружении и может иметь свои собственные зависимости, не влияя на другие инструменты.

Установка pipx

Если pipx ещё не установлен, его можно установить через pip или через системный пакетный менеджер:

# Через pip (рекомендуется в виртуальное окружение)
pip install pipx
pipx ensurepath  # добавить ~/.local/bin в PATH

# macOS — через Homebrew
brew install pipx
pipx ensurepath

# Linux — через apt (Debian/Ubuntu)
sudo apt install pipx
pipx ensurepath

# Linux — через dnf (Fedora)
sudo dnf install pipx
pipx ensurepath

Установка Ruff через pipx

# Установить Ruff
pipx install ruff

# Проверить установку
ruff --version

# Обновить Ruff
pipx upgrade ruff

# Удалить Ruff
pipx uninstall ruff

# Запустить временную версию (без установки)
pipx run ruff --version
pipx run ruff check main.py

Обратите внимание на команду pipx run — она позволяет запустить Ruff без предварительной установки. pipx создаст временное изолированное окружение, установит туда Ruff, выполнит команду и затем удалит окружение. Это полезно для разовых запусков, например, в CI-скриптах или при тестировании новой версии. Однако для постоянного использования лучше выполнить полную установку через pipx install ruff, так как каждая команда pipx run тратит время на создание и удаление окружения.

Установка конкретной версии через pipx

# Установить конкретную версию
pipx install ruff==0.6.0

# Установить определённую версию
pipx install ruff==0.5.0

# Обновить до конкретной версии
pipx upgrade ruff==0.7.0

# Посмотреть список установленных инструментов
pipx list

pipx хранит все установленные инструменты в директории ~/.local/pipx/venvs/. Каждый инструмент находится в отдельном виртуальном окружении. С помощью команды pipx list вы можете увидеть список всех установленных инструментов, их версии и расположение. Это особенно удобно, когда у вас установлено много Python-инструментов и нужно быстро проверить их состояние.

Ruff распространяется как единственный самодостаточный бинарный файл (standalone binary) для всех основных платформ. Это означает, что вы можете установить Ruff без Python, без pip и без каких-либо зависимостей — просто скачав и запустив скрипт установки. Этот способ особенно полезен для CI-образов, Docker-контейнеров и минимальных окружений, где не установлен Python или вы хотите избежать лишних шагов.

Официальный скрипт установки автоматически определяет вашу операционную систему и архитектуру процессора, скачивает подходящий бинарный файл с GitHub Releases и помещает его в ~/.local/bin или ~/.cargo/bin.

# Установить через официальный скрипт (macOS/Linux)
curl -LsSf https://astral.sh/ruff/install.sh | sh

# После установки нужно перезагрузить PATH
source ~/.cargo/env  # или переоткрыть терминал

# Проверить
ruff --version

Скрипт делает следующее: он проверяет наличие curl или wget, определяет архитектуру системы (x86_64, aarch64 и т.д.), скачивает архив с последней версией Ruff с GitHub, распаковывает его и помещает бинарный файл в ~/.cargo/bin/ruff (или другую подходящую директорию). Если в системе установлен Cargo, скрипт использует его директорию для бинарных файлов; в противном случае используется ~/.local/bin.

Ручная загрузка бинарного файла

Если вы предпочитаете не запускать скрипты из интернета (что вполне разумно с точки зрения безопасности), вы можете скачать бинарный файл вручную со страницы релизов на GitHub:

# macOS (Intel)
curl -Lo ruff.tar.gz https://github.com/astral-sh/ruff/releases/latest/download/ruff-x86_64-apple-darwin.tar.gz

# macOS (Apple Silicon)
curl -Lo ruff.tar.gz https://github.com/astral-sh/ruff/releases/latest/download/ruff-aarch64-apple-darwin.tar.gz

# Linux (x86_64)
curl -Lo ruff.tar.gz https://github.com/astral-sh/ruff/releases/latest/download/ruff-x86_64-unknown-linux-gnu.tar.gz

# Linux (aarch64)
curl -Lo ruff.tar.gz https://github.com/astral-sh/ruff/releases/latest/download/ruff-aarch64-unknown-linux-gnu.tar.gz

# Windows (x86_64) — через PowerShell
# Invoke-WebRequest -Uri https://github.com/astral-sh/ruff/releases/latest/download/ruff-x86_64-pc-windows-msvc.zip -OutFile ruff.zip

# Распаковать
tar -xzf ruff.tar.gz

# Переместить в директорию из PATH
mv ruff/ruff ~/.local/bin/
# или
sudo mv ruff/ruff /usr/local/bin/

# Проверить
ruff --version

Вы также можете найти полный список доступных архитектур и платформ на странице релизов Ruff на GitHub: https://github.com/astral-sh/ruff/releases. Для Windows бинарные файлы поставляются в формате ZIP, для macOS и Linux — в формате tar.gz. Каждый архив содержит единственный исполняемый файл ruff (или ruff.exe для Windows), который не требует никаких дополнительных библиотек для запуска.

Преимущества standalone-установки

Standalone-бинарный файл Ruff — это полностью самодостаточный исполняемый файл, не требующий установленного Python или каких-либо других зависимостей. Это делает его идеальным выбором для CI-окружений, где каждая секунда установки имеет значение. Бинарный файл Ruff имеет размер около 20-30 МБ (в зависимости от платформы) и содержит всё необходимое для работы: парсер Python, линтер, форматтер и все правила. Никаких runtime-зависимостей, никаких виртуальных окружений — просто скомпилированный Rust-бинарник.

Кроме того, standalone-версия часто выходит быстрее, чем версия на PyPI, так как не требует дополнительной публикации на PyPI. Если вы следите за разработкой Ruff и хотите получить новую версию сразу после её выхода, используйте standalone-скрипт или Cargo.

Если вы разработчик на Rust или хотите собрать Ruff из исходного кода, вы можете использовать Cargo — пакетный менеджер Rust. Этот способ даёт вам максимальный контроль над процессом сборки и позволяет использовать самую свежую версию из git-репозитория (например, если нужное исправление ещё не вышло в релизе). Однако учтите, что сборка из исходного кода требует установленного Rust Toolchain и занимает несколько минут.

# Установка через Cargo (из crates.io)
cargo install ruff

# Установка конкретной версии
cargo install ruff@0.6.0

# Установка из GitHub (ветка main, самая свежая)
cargo install --git https://github.com/astral-sh/ruff ruff

# Установка из определённого коммита
cargo install --git https://github.com/astral-sh/ruff --rev abc1234 ruff

# Проверить установку
ruff --version

Сборка Ruff через Cargo занимает от 2 до 5 минут на современном процессоре, так как компилируется весь проект на Rust. Компилятор Rust оптимизирует бинарный файл под вашу конкретную архитектуру, что может дать небольшой прирост производительности по сравнению с предварительно собранными бинарными файлами. Однако для большинства пользователей разница в производительности будет незаметна, поэтому использование Cargo рекомендуется только для разработчиков Rust или тех, кому нужна самая свежая версия из git.

Установка Rust Toolchain

Если у вас ещё не установлен Rust, вы можете установить его с помощью официального скрипта rustup:

# Установить Rust Toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Активировать в текущей сессии
source ~/.cargo/env

# Проверить установку
rustc --version
cargo --version

Если вы используете Homebrew — популярный пакетный менеджер для macOS (и Linux в последних версиях), — установка Ruff выполняется одной командой. Homebrew автоматически загружает предварительно собранный бинарный файл (bottle) и размещает его в /usr/local/bin (на macOS Intel) или /opt/homebrew/bin (на macOS Apple Silicon).

# Установка
brew install ruff

# Проверить
ruff --version

# Обновить (если уже установлен)
brew upgrade ruff

# Получить информацию о пакете
brew info ruff

# Удалить
brew uninstall ruff

На момент написания этого урока в Homebrew доступна актуальная версия Ruff, и она обновляется в течение нескольких часов после выхода нового релиза. Вы можете проверить, какая версия доступна в Homebrew, с помощью команды brew info ruff, которая покажет версию, зависимости (у Ruff их нет), а также путь к установленному бинарному файлу. Homebrew также автоматически управляет обновлениями — вы можете выполнить brew upgrade ruff для обновления до последней версии, доступной в репозитории.

Обратите внимание, что установка через Homebrew не добавляет Ruff в файл зависимостей вашего проекта. Ruff будет установлен глобально в систему. Если вы работаете в команде, лучше добавить Ruff как dev-зависимость через pip или uv, чтобы все разработчики использовали одну и ту же версию. Homebrew же отлично подходит для личного использования и быстрого старта.

Если вы работаете в экосистеме Conda (Anaconda, Miniconda, Miniforge), вы можете установить Ruff из канала conda-forge. Conda — это популярный менеджер пакетов в сообществе data science, и Ruff доступен в репозитории conda-forge, где поддерживается сообществом. Установка через Conda особенно удобна, если вы уже используете Conda для управления окружениями и не хотите смешивать Python-окружения.

# Установка из conda-forge
conda install -c conda-forge ruff

# Или если вы уже настроили conda-forge как канал
conda install ruff

# Установка в конкретное окружение
conda install -n myenv -c conda-forge ruff

# Создать окружение с Ruff
conda create -n linting -c conda-forge ruff

# Проверить
ruff --version

# Обновить
conda update -c conda-forge ruff

# Удалить
conda remove ruff

Conda-пакет Ruff поддерживается сообществом через conda-forge и обычно обновляется в течение нескольких дней после выхода новой версии на GitHub. Версия в conda-forge может немного отставать от последней версии на PyPI или GitHub, но это отставание обычно составляет не более 1-2 дней. Если вам нужна абсолютно последняя версия, используйте pip, uv или standalone-бинарный файл.

Важное преимущество Conda в том, что она отлично работает на Windows, macOS и Linux, и позволяет легко переключаться между разными окружениями с разными версиями Python. Если вы data scientist или ML-инженер, использующий Conda, установка Ruff через conda-forge будет наиболее естественным способом.

pkgx (ранее pkgxdev) — это современный кроссплатформенный менеджер пакетов, который не требует установки — он просто загружает и запускает программное обеспечение на лету. pkgx не требует прав суперпользователя, не требует демонов и не добавляет ничего в PATH до момента использования. Вы можете использовать pkgx для запуска Ruff без предварительной установки: pkgx автоматически загрузит и закэширует нужную версию Ruff при первом запуске.

# Установка pkgx (macOS/Linux)
curl -fsSL https://pkgx.sh | sh

# Запуск Ruff через pkgx (автоматическая загрузка)
pkgx ruff --version
pkgx ruff check main.py

# Запуск конкретной версии
pkgx ruff@0.6.0 --version

# Создание алиаса для постоянного использования
pkgx integrate  # добавляет pkgx в shell

# После интеграции ruff становится глобально доступным
ruff --version

pkgx — это интересная альтернатива традиционным менеджерам пакетов. Он не требует установки Python, Rust или других зависимостей. pkgx просто загружает бинарный файл Ruff из своего репозитория и запускает его. Если вы часто работаете на разных машинах и не хотите устанавливать инструменты вручную, pkgx может быть отличным решением. Однако pkgx всё ещё относительно молодой инструмент и может быть незнаком многим разработчикам, поэтому в командной работе стоит согласовать его использование с коллегами.

Пользователи Arch Linux могут установить Ruff как из официального репозитория (community), так и из AUR (Arch User Repository). В официальном репозитории Ruff доступен как пакет ruff, который можно установить через pacman. В AUR доступен пакет ruff-bin, который загружает предварительно собранный бинарный файл с GitHub, что ускоряет установку.

Установка через pacman (официальный репозиторий)

# Установка из официального репозитория
sudo pacman -S ruff

# Обновление
sudo pacman -Syu ruff

# Проверить
ruff --version

# Удалить
sudo pacman -R ruff

Установка из AUR (через yay или paru)

Если вы используете AUR-помощник (yay, paru или другой), вы можете установить Ruff с предварительно собранным бинарным файлом. Пакет ruff-bin загружает готовый бинарный файл с GitHub, что значительно быстрее, чем сборка из исходников:

# Через yay
yay -S ruff-bin

# Через paru
paru -S ruff-bin

# Проверить
ruff --version

Обратите внимание, что пакет ruff в официальном репозитории может отставать от последней версии на несколько дней, так как требует сборки из исходного кода и прохождения проверки. Пакет ruff-bin из AUR обычно обновляется быстрее, так как просто загружает готовый бинарный файл. Если вам нужна свежая версия, используйте AUR; если вам важнее стабильность и проверка пакета официальным мейнтейнером, используйте pacman.

Для пользователей Alpine Linux (включая Docker-образы на основе Alpine) Ruff доступен в официальном репозитории сообщества (community repository). Alpine — это минималистичный дистрибутив Linux, который часто используется для создания лёгких Docker-образов. Установка Ruff через apk — это самый быстрый способ добавить линтер в Alpine-контейнер.

# Включить репозиторий community (если не включён)
# Раскомментируйте соответствующую строку в /etc/apk/repositories

# Установка Ruff
sudo apk add ruff

# Проверить
ruff --version

# Обновить
sudo apk upgrade ruff

# Удалить
sudo apk del ruff

Пакет Ruff в Alpine собирается и поддерживается сообществом. На момент написания урока Ruff доступен в репозитории Alpine Edge (ветка развития) и обычно переносится в стабильные версии Alpine в течение нескольких недель после выхода релиза. Если вам нужна более свежая версия Ruff в Alpine, вы можете использовать standalone-бинарный файл или pip в виртуальном окружении.

Обратите внимание, что Alpine использует musl libc вместо glibc, поэтому standalone-бинарные файлы Ruff для Linux (x86_64-unknown-linux-gnu) не будут работать на Alpine. Для Alpine нужна специальная сборка: x86_64-unknown-linux-musl (или соответствующая архитектура). Официальный скрипт установки (curl -LsSf https://astral.sh/ruff/install.sh | sh) автоматически определяет использование musl и скачивает правильную сборку.

Если вы используете Docker для разработки или CI, вы можете установить Ruff в образ несколькими способами. Мы рассмотрим установку на разных базовых образах: python, ubuntu, alpine и scratch. Выбор базового образа зависит от ваших требований к размеру образа и скорости сборки.

Установка через pip в Dockerfile (на базе python)

FROM python:3.12-slim

# Установка Ruff
RUN pip install --no-cache-dir ruff

# Проверка
RUN ruff --version

Установка через standalone-бинарник (минимальный образ)

FROM python:3.12-slim

# Установка Ruff через официальный скрипт
RUN curl -LsSf https://astral.sh/ruff/install.sh | sh

# Добавляем в PATH
ENV PATH="/root/.cargo/bin:${PATH}"

# Проверка
RUN ruff --version

Установка в многоступенчатой сборке (multistage build)

Многоступенчатая сборка (multistage build) позволяет создать минимальный финальный образ, скопировав только бинарный файл Ruff из промежуточного образа. Это даёт наименьший размер конечного образа Docker:

# Этап 1: установка Ruff
FROM python:3.12-slim AS builder
RUN pip install --no-cache-dir ruff
# Ищем, где установлен ruff
RUN which ruff

# Этап 2: финальный образ
FROM python:3.12-slim
COPY --from=builder /usr/local/bin/ruff /usr/local/bin/ruff
RUN ruff --version

Если вы используете Alpine в качестве базового образа для минимального размера:

FROM alpine:3.19

# Установка Ruff через apk
RUN apk add --no-cache ruff

# Проверка
RUN ruff --version

Установка на scratch-образе

Для самых минимальных образов можно использовать scratch (пустой образ) и скопировать туда только бинарный файл Ruff. Однако учтите, что Ruff может требовать некоторые системные библиотеки (libc, libgcc), поэтому scratch-образ подходит не для всех конфигураций. Вместо scratch рекомендуется использовать distroless или alpine:

FROM alpine:3.19 AS builder
RUN apk add --no-cache curl
RUN curl -LsSf https://astral.sh/ruff/install.sh | sh

FROM gcr.io/distroless/base
COPY --from=builder /root/.cargo/bin/ruff /usr/local/bin/ruff
ENTRYPOINT ["ruff"]

Официальный Docker-образ Ruff также публикуется на GitHub Container Registry (ghcr.io/astral-sh/ruff). Вы можете использовать его как базовый образ или как временный контейнер для запуска линтинга:

# Запуск Ruff через официальный Docker-образ
docker run --rm -v $(pwd):/src ghcr.io/astral-sh/ruff check /src

# С тегами версий
docker run --rm -v $(pwd):/src ghcr.io/astral-sh/ruff:0.6.0 check /src

# Запуск форматирования
docker run --rm -v $(pwd):/src ghcr.io/astral-sh/ruff:latest format /src

Использование Docker-образа удобно, когда вы не хотите устанавливать Ruff локально или когда нужно гарантировать изолированное окружение для линтинга. Однако учтите, что каждый запуск Docker-контейнера требует времени на загрузку образа (если он ещё не закэширован). Для локальной разработки всё же предпочтительнее установить Ruff напрямую.

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

# Проверка версии
ruff --version
# Пример вывода: ruff 0.8.0

# Справка по всем командам
ruff help

# Проверка конкретной команды
ruff check --help
ruff format --help

# Быстрый тест — создадим временный файл и проверим его
echo "x=1" | ruff check --stdin-filename test.py -
# Должен показать ошибку E225

# Проверить, где установлен Ruff
which ruff
# Пример: /usr/local/bin/ruff (macOS Homebrew)
# или: ~/.local/bin/ruff (pipx)
# или: ~/.cargo/bin/ruff (Cargo/standalone)

# Проверить версию Python, для которой установлен Ruff
ruff --version --output-format json

Подробная проверка установки

Вот несколько более детальных проверок, которые помогут убедиться, что Ruff работает корректно и настроен правильно:

# Проверить, что Ruff видит Python-файлы
echo 'import os; print("hello")' > /tmp/test_ruff.py
ruff check /tmp/test_ruff.py
# Должен показать: Found 0 errors (если нет других ошибок)
# Или ошибки, если файл содержит проблемы
rm /tmp/test_ruff.py

# Проверить форматирование
echo 'x=1' > /tmp/test_format.py
ruff format /tmp/test_format.py --check
ruff format /tmp/test_format.py
cat /tmp/test_format.py  # должно стать "x = 1"
rm /tmp/test_format.py

# Проверить версию в JSON
ruff version --output-format json 2>/dev/null || ruff --version

# Проверить доступные правила
ruff check --show-settings 2>/dev/null | head -20
ruff check --show-fixes 2>/dev/null | head -10

Иногда вам может понадобиться установить не последнюю, а конкретную версию Ruff. Это может быть нужно для совместимости с существующими настройками проекта, для воспроизводимых сборок в CI или для тестирования новой версии перед обновлением во всём проекте. Каждый способ установки поддерживает указание конкретной версии.

Указание версии через pip

# Установка конкретной версии
pip install ruff==0.6.0

# Установка с минимальной версией
pip install "ruff>=0.5.0,<0.7.0"

# Установка pre-release версии
pip install --pre ruff

Указание версии через uv

# Добавить конкретную версию
uv add --dev ruff==0.6.0

# Установить конкретную версию глобально
uv tool install ruff==0.6.0

# Установка pre-release
uv tool install ruff --pre

Указание версии через standalone-скрипт

Standalone-скрипт по умолчанию устанавливает последнюю версию, но вы можете указать конкретную версию через переменную окружения или URL:

# Установка конкретной версии через переменную окружения
export RUFF_VERSION=0.6.0
curl -LsSf https://astral.sh/ruff/install.sh | sh

# Или прямая загрузка конкретной версии
curl -Lo ruff.tar.gz \
  "https://github.com/astral-sh/ruff/releases/download/0.6.0/ruff-x86_64-unknown-linux-gnu.tar.gz"
tar -xzf ruff.tar.gz
sudo mv ruff/ruff /usr/local/bin/
rm -rf ruff ruff.tar.gz

Указание версии через Cargo

# Конкретная версия из crates.io
cargo install ruff@0.6.0

# Конкретный коммит из GitHub
cargo install --git https://github.com/astral-sh/ruff \
  --rev a1b2c3d4e5f6 ruff

# Конкретная ветка
cargo install --git https://github.com/astral-sh/ruff \
  --branch main ruff

Просмотр доступных версий

Чтобы узнать, какие версии Ruff доступны для установки, вы можете воспользоваться следующими командами:

# Просмотр версий на PyPI (через pip)
pip index versions ruff

# Просмотр версий через PyPI JSON API
curl -s https://pypi.org/pypi/ruff/json | \
  python3 -c "import sys,json;print('\n'.join(json.load(sys.stdin)['releases'].keys()))"

# Просмотр версий через uv
uv tool list --version  # если установлен

# Просмотр релизов на GitHub (через API)
curl -s https://api.github.com/repos/astral-sh/ruff/releases | \
  python3 -c "import sys,json;[print(r['tag_name']) for r in json.load(sys.stdin)]" | head -20

Ruff активно развивается, и новые версии выходят регулярно (иногда несколько раз в неделю). Обновления включают новые правила, исправления ошибок, оптимизацию производительности и поддержку новых версий Python. Рекомендуется регулярно обновлять Ruff, чтобы получать последние улучшения и исправления.

Каждый способ установки имеет свою команду для обновления. Вот как обновить Ruff для каждого метода:

# pip
pip install --upgrade ruff

# pipx
pipx upgrade ruff

# uv (глобальный инструмент)
uv tool upgrade ruff

# uv (dev-зависимость проекта)
uv add --dev ruff@latest

# Cargo
cargo install ruff
# или для обновления из GitHub
cargo install --git https://github.com/astral-sh/ruff ruff

# Homebrew
brew upgrade ruff

# Conda
conda update -c conda-forge ruff

# Arch Linux (pacman)
sudo pacman -Syu ruff

# Alpine Linux
sudo apk upgrade ruff

# Standalone (переустановка)
curl -LsSf https://astral.sh/ruff/install.sh | sh

Автоматическое обновление

Вы можете автоматизировать обновление Ruff, добавив соответствующую команду в ваш скрипт настройки окружения или CI-пайплайн. Например, можно периодически запускать проверку версии и обновление через cron (на macOS/Linux) или через запланированное задание (на Windows):

# Пример скрипта для автоматического обновления (update_ruff.sh)
#!/bin/bash
# Сравнить текущую версию с последней доступной
CURRENT=$(ruff --version 2>/dev/null | cut -d' ' -f2 || echo "none")
LATEST=$(curl -s https://api.github.com/repos/astral-sh/ruff/releases/latest | \
  python3 -c "import sys,json;print(json.load(sys.stdin)['tag_name'].lstrip('v'))" 2>/dev/null)

if [ "$CURRENT" != "$LATEST" ] && [ -n "$LATEST" ]; then
  echo "Обновление Ruff: $CURRENT -> $LATEST"
  pip install --upgrade ruff
fi

Проверка совместимости перед обновлением

Перед обновлением Ruff в рабочем проекте рекомендуется проверить, не появилось ли в новой версии изменений, которые могут сломать вашу кодовую базу. Новые версии Ruff могут добавлять новые правила, которые будут применяться по умолчанию. Вот как безопасно проверить новую версию:

# Установить новую версию в виртуальное окружение
python -m venv /tmp/ruff-test
source /tmp/ruff-test/bin/activate
pip install ruff==0.8.0

# Запустить проверку на проекте (без изменений!)
ruff check /path/to/your/project

# Сравнить с текущей версией
deactivate
ruff check /path/to/your/project

# Удалить тестовое окружение
rm -rf /tmp/ruff-test

Если вам больше не нужен Ruff, его можно легко удалить. Команда удаления зависит от способа установки:

# pip
pip uninstall ruff
# Если установлен через --user
pip uninstall --user ruff

# pipx
pipx uninstall ruff

# uv (глобальный инструмент)
uv tool uninstall ruff

# uv (dev-зависимость проекта)
uv remove --dev ruff

# Cargo
cargo uninstall ruff

# Homebrew
brew uninstall ruff

# Conda
conda remove ruff

# Arch Linux (pacman)
sudo pacman -R ruff

# Alpine Linux
sudo apk del ruff

# Standalone (ручное удаление)
rm ~/.local/bin/ruff
# или
rm ~/.cargo/bin/ruff

Полная очистка

Если вы хотите полностью удалить все следы Ruff из системы, выполните следующие дополнительные шаги:

# Проверить, не осталось ли где-то ещё копий Ruff
which ruff 2>/dev/null || echo "ruff не найден в PATH"

# Поиск всех установленных копий Ruff
find /usr/local/bin /usr/bin ~/.local/bin ~/.cargo/bin -name "ruff" 2>/dev/null

# Удаление кэша Ruff (если есть)
rm -rf ~/.cache/ruff

# Удаление конфигурации Ruff из проекта
# Удалите секцию [tool.ruff] из pyproject.toml или .ruff.toml

После удаления Ruff рекомендуется перезагрузить терминал или выполнить hash -d ruff (в bash/zsh), чтобы очистить кэш команд, если он был. Если Ruff был установлен через pipx или uv tool, убедитесь, что директория с исполняемыми файлами (обычно ~/.local/bin) больше не содержит ссылок на Ruff.

Хотя установка Ruff обычно проходит гладко, иногда могут возникнуть проблемы. Вот наиболее частые проблемы и способы их решения.

Проблема: команда ruff не найдена (command not found)

Самая частая проблема после установки — система не может найти команду ruff. Это обычно означает, что директория с установленным Ruff не добавлена в переменную окружения PATH. Решение зависит от способа установки:

# Найти, куда установился Ruff
# Для pip (--user)
python3 -m site --user-base
# Примерный вывод: /Users/user/Library/Python/3.12/bin (macOS)
# или: /home/user/.local/bin (Linux)

# Для pipx
pipx ensurepath

# Для uv tool
# uv добавляет ~/.local/bin в PATH автоматически

# Для standalone / Cargo
source ~/.cargo/env
# Или добавьте в ~/.bashrc / ~/.zshrc:
export PATH="$HOME/.cargo/bin:$PATH"

# Для Homebrew на macOS Apple Silicon
export PATH="/opt/homebrew/bin:$PATH"

# Проверить PATH
echo $PATH | tr ':' '\n'

Проблема: Permission denied при установке через pip

Если вы получаете ошибку "Permission denied" при установке через pip, это означает, что вы пытаетесь установить пакет в глобальное окружение Python без прав суперпользователя. Никогда не используйте sudo pip install — это может нарушить работу системного Python. Вместо этого используйте флаг --user или установите в виртуальное окружение:

# Правильно: установка для текущего пользователя
pip install --user ruff

# Правильно: установка в виртуальное окружение
python -m venv .venv
source .venv/bin/activate
pip install ruff

# Неправильно: НЕ ИСПОЛЬЗУЙТЕ sudo pip install
# sudo pip install ruff  # НЕТ!

Проблема: ошибка при сборке из исходного кода (Cargo)

При установке через Cargo могут возникнуть ошибки компиляции. Вот наиболее частые причины и решения:

# 1. Недостаточно памяти (OOM)
# Решение: ограничить количество параллельных потоков компиляции
CARGO_BUILD_JOBS=2 cargo install ruff

# 2. Отсутствует компилятор C/C++
# На Linux: sudo apt install build-essential
# На macOS: xcode-select --install

# 3. Слишком старая версия Rust
rustup update

# 4. Конфликт с уже установленной версией
cargo uninstall ruff && cargo install ruff

Проблема: Ruff работает медленно

Если Ruff работает медленно, возможно, вы используете версию, установленную через pip в виртуальном окружении, и бинарный файл не оптимизирован для вашей архитектуры. Попробуйте установить standalone-бинарный файл или использовать Cargo для сборки под вашу архитектуру. Также проверьте, не исключены ли большие директории (например, виртуальные окружения, node_modules) из проверки. Ruff по умолчанию уважает .gitignore, но вы можете явно указать исключения в конфигурации.

Проблема: конфликт с Flake8 или другими линтерами

Ruff спроектирован как замена Flake8, pylint, isort и Black. Если у вас уже установлены эти инструменты, они могут конфликтовать с Ruff в CI или pre-commit хуках. Рекомендуется заменить их на Ruff, так как Ruff поддерживает те же правила (через плагины) и работает значительно быстрее. Удалите старые линтеры и настройте Ruff как единственный инструмент для линтинга и форматирования.

Проблема: ошибка SSL при установке через pip

Если вы получаете SSL-ошибки при установке через pip (например, в корпоративной сети или за прокси), попробуйте следующие решения:

# Использовать доверенный хост
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org ruff

# Использовать прокси
pip install --proxy http://user:pass@proxy:port ruff

# Использовать зеркало PyPI (например, для России)
pip install -i https://mirror.yandex.ru/pypi/simple ruff

# Или установить через standalone-скрипт (не требует PyPI)
curl -LsSf https://astral.sh/ruff/install.sh | sh

Проблема: Ruff не работает в Git Bash (Windows)

На Windows при использовании Git Bash могут возникнуть проблемы с путями. Ruff ожидает Unix-подобные пути, но Git Bash может передавать Windows-пути. Решение: используйте PowerShell или cmd для запуска Ruff, или устанавливайте Ruff через standalone-бинарный файл для Windows.

Проблема: неверная архитектура (под M1/Rosetta)

На macOS с процессорами Apple Silicon (M1, M2, M3) убедитесь, что вы установили версию Ruff для ARM64. Если вы используете терминал под Rosetta 2, pip может установить версию для Intel x86_64. Чтобы избежать этого, убедитесь, что вы используете нативный терминал ARM64:

# Проверить архитектуру Python
python3 -c "import platform; print(platform.machine())"
# Должно быть: arm64 (а не x86_64)

# Если вы под Rosetta, запустите терминал как arm64:
# В Finder: Приложения -> Служебные программы -> Терминал (правый клик -> Получить информацию)
# Или установите standalone-бинарник для aarch64
curl -LsSf https://astral.sh/ruff/install.sh | sh

Проблема: ошибка "No such file or directory" при запуске ruff

Если вы установили Ruff через standalone-скрипт на Linux и получаете ошибку "No such file or directory" при запуске, это может быть связано с тем, что бинарный файл собран для другой версии glibc. Убедитесь, что вы скачали правильную версию для вашего дистрибутива. Если ваш дистрибутив использует musl (Alpine), скачайте версию x86_64-unknown-linux-musl. Если вы используете старый дистрибутив с устаревшей glibc, попробуйте собрать Ruff из исходного кода через Cargo.

Windows

На Windows установка Ruff возможна через pip (в командной строке или PowerShell), через pipx, через standalone-бинарный файл, через Conda, а также через пакетный менеджер winget (начиная с определённых версий Windows 10 и 11). При установке через pip на Windows убедитесь, что Python и pip добавлены в PATH. Если вы используете WSL (Windows Subsystem for Linux), рекомендуется установить Ruff внутри WSL — это обеспечит максимальную совместимость с Linux-инструментами.

Особенности Windows: при использовании pip в PowerShell может потребоваться установка Microsoft C++ Build Tools, если pip пытается собрать пакет из исходного кода (вместо загрузки wheel). На практике это случается редко, так как Ruff предоставляет wheel для Windows. Если вы видите ошибку сборки, скорее всего, pip пытается собрать одну из зависимостей, а не сам Ruff. В этом случае используйте standalone-бинарный файл.

:: Windows cmd
pip install ruff
ruff --version

:: PowerShell
pip install ruff
ruff --version

:: Через winget (Windows 10+)
winget install ruff

:: Через Scoop
scoop install ruff

:: Через Chocolatey
choco install ruff

macOS

На macOS Ruff отлично работает как на Intel (x86_64), так и на Apple Silicon (ARM64, M1/M2/M3). Рекомендуемый способ установки на macOS — через Homebrew, так как он автоматически устанавливает правильную архитектуру. Если вы используете pip, убедитесь, что ваша версия Python поддерживает multiprocessing и что вы используете нативный терминал ARM64 (не Rosetta) для достижения максимальной производительности.

Если вы устанавливаете Ruff на macOS через standalone-скрипт, скрипт автоматически определит архитектуру и скачает правильный бинарный файл (ruff-aarch64-apple-darwin для ARM64, ruff-x86_64-apple-darwin для Intel). На macOS также доступна установка через MacPorts:

# Через MacPorts
sudo port install ruff

# Проверка архитектуры
file $(which ruff)
# Пример: .../ruff: Mach-O 64-bit executable arm64
# или: .../ruff: Mach-O 64-bit executable x86_64

Linux

На Linux Ruff доступен через большинство популярных пакетных менеджеров. Выбор способа установки зависит от вашего дистрибутива:

# Debian / Ubuntu
sudo apt install ruff

# Fedora / RHEL / CentOS
sudo dnf install ruff

# openSUSE
sudo zypper install ruff

# Void Linux
sudo xbps-install -S ruff

# NixOS
nix-env -iA nixpkgs.ruff
# или
nix profile install nixpkgs#ruff

На Linux также доступны AppImage и Flatpak для Ruff, хотя они менее распространены. Если вы используете контейнерную среду (Docker, Podman), рекомендуется устанавливать Ruff внутри контейнера, а не на хост-машине.

Установка Ruff в CI-пайплайнах должна быть быстрой и воспроизводимой. Вот лучшие практики для популярных CI-систем. Главное правило: в CI всегда указывайте конкретную версию Ruff, чтобы избежать неожиданных изменений в поведении линтера при выходе новой версии.

GitHub Actions

Для GitHub Actions рекомендуется использовать официальное действие astral-sh/ruff-action, которое автоматически устанавливает нужную версию Ruff и настраивает кэширование:

name: Lint
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          version: "0.8.0"  # указать конкретную версию
      - run: ruff check --output-format=github
      - run: ruff format --check

Если вы предпочитаете устанавливать Ruff вручную (например, если используете нестандартный runner), вот как это сделать:

name: Lint (manual setup)
on: [push]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Ruff
        run: |
          curl -LsSf https://astral.sh/ruff/0.8.0/install.sh | sh
          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
      - name: Run Ruff
        run: ruff check .

GitLab CI

ruff-lint:
  image: python:3.12-slim
  before_script:
    - pip install ruff==0.8.0
  script:
    - ruff check .
  only:
    - merge_requests
    - main

Jenkins

pipeline {
  agent any
  stages {
    stage('Lint') {
      steps {
        script {
          // Установка Ruff
          sh 'pip install ruff==0.8.0'
          // Запуск линтинга
          sh 'ruff check .'
        }
      }
    }
  }
}

CircleCI

version: 2.1
jobs:
  lint:
    docker:
      - image: cimg/python:3.12
    steps:
      - checkout
      - run:
          name: Install Ruff
          command: pip install ruff==0.8.0
      - run:
          name: Run Ruff
          command: ruff check .
workflows:
  lint:
    jobs:
      - lint

Pre-commit хуки

Ruff можно настроить как pre-commit хук, чтобы он автоматически проверял код перед каждым коммитом. Это помогает ловить ошибки до того, как они попадут в репозиторий:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

Лучшие практики для CI

Вот несколько рекомендаций по использованию Ruff в CI:

• Всегда фиксируйте версию Ruff — используйте ruff==0.8.0 вместо ruff, чтобы избежать неожиданных изменений при выходе новой версии.
• Используйте standalone-установку для скорости — в CI каждая секунда на счету. Standalone-бинарный файл устанавливается быстрее, чем через pip.
• Кэшируйте установку — в GitHub Actions используйте astral-sh/ruff-action, который автоматически кэширует бинарный файл Ruff между запусками.
• Разделяйте линтинг и форматирование — запускайте ruff check и ruff format --check отдельно, чтобы в логах было понятно, какой этап упал.
• Используйте --output-format — для GitHub Actions используйте --output-format=github, чтобы ошибки отображались прямо в интерфейсе Pull Request.
• Не блокируйте CI на все ошибки сразу — если в проекте много старых ошибок, начните с ruff check --exit-zero, чтобы CI проходил, но вы видели все проблемы.

В зависимости от ваших потребностей, вы можете выбрать наиболее подходящий способ установки. Вот краткое сравнение всех методов:

Выбор способа установки Ruff зависит от вашей ситуации. Вот краткие рекомендации:

• Я новичок, хочу просто попробовать Ruff — используйте standalone-скрипт (curl -LsSf https://astral.sh/ruff/install.sh | sh). Это самый быстрый способ начать работу без установки дополнительных инструментов.
• Я работаю над Python-проектом с командой — используйте uv, добавив Ruff как dev-зависимость. Это обеспечит одинаковую версию для всех разработчиков и быструю установку.
• Я хочу глобальный инструмент, доступный из любого места — используйте pipx или uv tool. Оба способа создают изолированное окружение и делают Ruff глобально доступным.
• Я настраиваю CI/CD — используйте standalone-бинарный файл или официальное GitHub Action. Это самый быстрый и воспроизводимый способ.
• Я использую macOS — установка через Homebrew (brew install ruff) — самый естественный и простой способ.
• Я разработчик на Rust — используйте Cargo (cargo install ruff), чтобы всегда иметь самую свежую версию.
• Я data scientist, использую Conda — установите Ruff через conda-forge (conda install -c conda-forge ruff).
• Мне нужна изолированная среда без Python — standalone-бинарный файл не требует Python и компиляторов. Просто скачайте и запускайте.

Независимо от выбранного способа, установка Ruff занимает всего несколько секунд (за исключением сборки через Cargo). После установки вы можете сразу приступить к использованию линтера и форматтера. В следующем уроке мы научимся запускать Ruff на реальном коде и читать его вывод.