اگر هر بار قبل از کامیت، با Flake8 خطاهای تکراری، با Black کشمکش فرمت و با isort مرتب‌سازی importها وقت تلف می‌کنید، Ruff پایان این سه‌گانه فرسایشی است. Ruff یک لینتر و فرمت‌کننده فوق‌سریع نوشته‌شده با Rust است که همه قوانین Flake8، isort، pyupgrade و حتی بخشی از Pylint را در یک ابزار 10 تا 100 برابر سریع‌تر ادغام می‌کند و با یک دستور، کد شلخته پایتون را تمیز، یکدست و آماده ریویو تحویل می‌دهد — ایده‌آل برای پروژه‌های هوش مصنوعی که سرعت و تمیزی کد حیاتی است. در ادامه نصب تا اتصال به VS Code را گام‌به‌گام می‌بینید.

Ruff در پایتون چیست و چرا سریع‌ترین ابزار لینت و فرمت است؟

Ruff جایگزین یکپارچه Flake8 + Black + isort است که روی Rust ساخته شده و به‌جای ثانیه‌ها، در میلی‌ثانیه کل ریپازیتوری را اسکن می‌کند؛ بیش از 800 قانون لینت را پشتیبانی، importها را مرتب و فرمت Black-compatible را خودکار اعمال می‌کند. برخلاف Flake8 که کند و افزونه‌محور است و Black که فقط فرمت می‌کند، Ruff با یک کانفیگ در pyproject.toml همه را یکجا حل می‌کند و روی پروژه‌های بزرگ FastAPI و دیتا 30 برابر سریع‌تر است. در ادامه نصب، اولین لینت، پیکربندی و مقایسه دقیق را می‌خوانید.

فهرست مطالب

پیش‌نیازها و نصب Ruff
اولین لینت با Ruff؛ از کد شلخته تا تمیز در 3 ثانیه
پیکربندی قدرتمند؛ pyproject.toml و انتخاب قوانین
فرمت خودکار با ruff format؛ تفاوت با Black
اتصال به VS Code و pre-commit؛ اتوماسیون تیمی
مقایسه Ruff با Flake8، Black و isort
کاربرد واقعی؛ لینت پایپ‌لاین AI و API با FastAPI
اشتباهات رایج هنگام کار با Ruff
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب Ruff

به پایتون 3.8 به بالا و یک محیط مجازی تمیز نیاز دارید. Ruff بدون وابستگی سنگین نصب می‌شود و روی ویندوز، مک و لینوکس یکسان کار می‌کند. اگر Poetry یا uv دارید، همان را استفاده کنید.

python -m venv .venv
# ویندوز: .venv\Scripts\activate
source .venv/bin/activate  # مک/لینوکس
pip install --upgrade ruff
ruff --version  # مثلا ruff 0.8.x
ruff check --help
ruff format --help

نسخه پیشنهادی: Ruff نسخه 0.8 به بالا؛ با pip show ruff یا ruff --version چک کنید.
مدیر بسته جایگزین: pipx install ruff برای نصب سراسری یا poetry add --group dev ruff و uv add --dev ruff.
ادیتور: VS Code با افزونه رسمی Ruff (charliermarsh.ruff) پیشنهاد می‌شود تا خطاها لحظه‌ای نمایش داده شود.
نکته: Ruff نیازی به Flake8 و Black جدا ندارد؛ اگر هستند، می‌توانید حذفشان کنید تا تداخل رخ ندهد.

اولین لینت با Ruff؛ از کد شلخته تا تمیز در 3 ثانیه

یک فایل نمونه با چند خطای کلاسیک بسازید تا قدرت Ruff را ببینید.

# messy.py
import os, sys
import numpy as np
import pandas as pd

def calc( x,y ):
    z= x+y
    print( z )
    unused = 123
    return z

ruff check messy.py
# خروجی نمونه:
# messy.py:1:1  E401  Multiple imports on one line
# messy.py:1:10 F401  `os` imported but unused
# messy.py:5:10 E201  Whitespace after '('
# messy.py:6:6  E225  Missing whitespace around operator
# messy.py:8:5  F841  Local variable `unused` is assigned but never used

تشخیص هم‌زمان: خطای استایل (E)، import استفاده‌نشده (F401) و متغیر اضافی (F841) را یکجا می‌گوید.
اصلاح خودکار: بسیاری از خطاها با پرچم --fix خودکار درست می‌شود.

ruff check --fix messy.py
ruff format messy.py
cat messy.py

# بعد از fix + format
import sys

import numpy as np
import pandas as pd


def calc(x, y):
    z = x + y
    print(z)
    return z

--fix: importهای اضافی را حذف و فاصله‌ها را طبق قانون درست می‌کند.
format: فرمت Black-compatible را اعمال می‌کند؛ فاصله‌ها، کوتیشن و طول خط یکدست می‌شود.
سرعت: روی 1000 فایل، Ruff در زیر 0.5 ثانیه تمام می‌شود؛ Flake8 چند ثانیه زمان می‌برد.

همین چرخه check --fix + format را روی پروژه واقعی با ruff check . اجرا کنید تا کل ریپو تمیز شود.

پیکربندی قدرتمند؛ pyproject.toml و انتخاب قوانین

قدرت Ruff در انتخاب دقیق قوانین است. به‌جای فایل‌های پراکنده .flake8 و isort.cfg، همه را در pyproject.toml متمرکز کنید.

[tool.ruff]
line-length = 88
target-version = "py310"
exclude = ["tests/fixtures", ".venv"]

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"]
fixable = ["ALL"]
unfixable = []

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

select: E/F برای pycodestyle/pyflakes، I برای isort، UP برای pyupgrade، B برای flake8-bugbear، SIM برای simplify.
ignore: اگر طول خط 88 را با Black هماهنگ کرده‌اید، E501 را نادیده بگیرید.
target-version: مثلا py310 تا سینتکس مدرن را پیشنهاد دهد.
exclude: پوشه مجازی و فیکسچرها را بیرون بگذارید تا اسکن سریع بماند.

ruff check . --statistics
ruff check . --output-format github  # برای CI

برای نادیده گرفتن خطی خاص، از کامنت # noqa: F401 یا # ruff: noqa استفاده کنید، اما حتی‌المقدور قانون را درست تنظیم کنید تا noqa پراکنده نشود.

فرمت خودکار با ruff format؛ تفاوت با Black

از نسخه 0.1 به بعد، Ruff فرمت‌کننده داخلی دارد که 99.9٪ با Black سازگار است اما 30 برابر سریع‌تر و بدون نیاز به نصب جداست.

ruff format .          # فرمت همه فایل‌ها
ruff format --check .  # فقط چک، بدون تغییر (برای CI)
ruff check --select I --fix .  # مرتب‌سازی import جداگانه

ویژگی	ruff format	Black
سرعت روی 1000 فایل	~0.3 ثانیه	~6 ثانیه
سازگاری	Black-compatible	مرجع
نیاز به isort جدا	خیر (I قانون داخلی)	بله
پیکربندی	همه در pyproject.toml	جدا

پیشنهاد تیمی: فقط ruff format را استاندارد کنید و Black را حذف کنید تا یک ابزار بماند.
CI: در گیت‌هاب اکشن، ruff format --check را به‌عنوان گیت اول بگذارید تا پول‌ریکوئست‌های بدفرمت رد شود.

اتصال به VS Code و pre-commit؛ اتوماسیون تیمی

لینت باید قبل از کامیت خودکار اجرا شود، نه بعد از ریویو.

VS Code

// .vscode/settings.json
{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

افزونه Ruff: از Marketplace نصب کنید؛ خطاها با اسکویگل قرمز و Fix با چراغ زرد ظاهر می‌شود.
formatOnSave: هر ذخیره، import مرتب و فرمت اعمال می‌شود.

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.4
    hooks:
      - id: ruff          # lint + --fix
        args: [--fix]
      - id: ruff-format   # format

pip install pre-commit
pre-commit install
pre-commit run --all-files

مزیت: حتی اگر توسعه‌دهنده فراموش کند، کامیت بدفرمت مسدود می‌شود.
به‌روزرسانی: با pre-commit autoupdate نسخه Ruff را هماهنگ نگه دارید.

اگر تست خودکار دارید، همین هوک را کنار آموزش Pytest برای پروژه AI اضافه کنید تا لینت و تست در یک قدم اجرا شود.

مقایسه Ruff با Flake8، Black و isort

معیار	Ruff	Flake8 + Black + isort	Pylint
سرعت	10-100x سریع‌تر (Rust)	کند، هر ابزار جدا	کندترین
تعداد قانون	800+ (یکجا)	~100 هرکدام	بسیار زیاد اما سنگین
اصلاح خودکار	بله، --fix گسترده	محدود (autopep8 جدا)	محدود
پیکربندی	یک فایل pyproject.toml	3 فایل جدا	پیچیده
فرمت	داخلی Black-compatible	Black جدا	ندارد
مناسب برای	پروژه AI/تیمی مدرن	پروژه قدیمی	تحلیل عمیق استاتیک

اگر پروژه‌تان قدیمی و Pylint‌محور است، Ruff را به‌تدریج با select محدود شروع کنید. اگر پروژه جدید FastAPI یا دیتا است، از روز اول Ruff را جایگزین کامل کنید. برای ترکیب با CLI حرفه‌ای، آموزش Typer برای CLI را ببینید تا لینت ابزار خط فرمان‌تان هم یکدست بماند.

کاربرد واقعی؛ لینت پایپ‌لاین AI و API با FastAPI

سناریو: یک سرویس FastAPI که دیتا را با Pandas می‌خواند و پیش‌بینی برمی‌گرداند. قبل از Ruff، importهای به‌هم‌ریخته و خطای سایه متغیر ریویو را کند می‌کرد.

# app.py (قبل)
from fastapi import FastAPI
import pandas as pd, numpy as np
from pydantic import BaseModel

app=FastAPI()
class Item(BaseModel):
    x:int
    y:int
def predict(item:Item):
    df=pd.DataFrame([item.dict()])
    result= df["x"]+df["y"]
    return {"sum":result[0]}

ruff check app.py
# E401, E231, F401, UP035 (dict -> model_dump)

ruff check --fix app.py
ruff format app.py
cat app.py

# app.py (بعد)
import numpy as np
import pandas as pd
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    x: int
    y: int


def predict(item: Item):
    df = pd.DataFrame([item.model_dump()])
    result = df["x"] + df["y"]
    return {"sum": result[0]}

E401 → رفع: importهای چندتایی جدا شد.
I → مرتب: importها به ترتیب استاندارد (stdlib، third-party، local) مرتب شد.
UP035: پیشنهاد model_dump به‌جای dict منسوخ Pydantic v2.
format: فاصله‌ها و annotationها یکدست شد.

ruff check . --fix
ruff format .
pytest -q  # اگر تست دارید، بعد از لینت اجرا کنید

همین دو دستور را در CI بگذارید تا هر پول‌ریکوئست، هم تمیز و هم سبز بماند.

اشتباهات رایج هنگام کار با Ruff

اجرای هم‌زمان Black و ruff format: هر دو فرمت می‌کنند و با هم می‌جنگند؛ یکی را حذف کنید و فقط ruff format را نگه دارید.
select = ["ALL"] بی‌محابا: همه 800 قانون را فعال نکنید؛ با E,F,I,UP,B,SIM شروع و به‌تدریج اضافه کنید تا تیم غرق هشدار نشود.
نادیده گرفتن target-version: بدون target-version = "py310" پیشنهادهای مدرن مثل X | Y به‌جای Union ظاهر نمی‌شود.
استفاده زیاد از # noqa: به‌جای پاشیدن noqa روی هر خط، قانون را در pyproject.toml با ignore تنظیم کنید.
عدم اتصال pre-commit: اجرای دستی فراموش می‌شود؛ حتما هوک ruff و ruff-format را نصب کنید تا قبل از پوش، کد تمیز شود.

سوالات متداول

آیا Ruff جایگزین کامل Flake8 و Black است؟

بله برای 95٪ پروژه‌ها. Ruff تمام قوانین مهم Flake8 (E,F) و مرتب‌سازی isort (I) و فرمت Black را پوشش می‌دهد. فقط اگر از پلاگین خاص Flake8 یا Black با تنظیم غیراستاندارد استفاده می‌کنید، سازگاری را با --diff مقایسه کنید و سپس مهاجرت کنید.

سرعت Ruff واقعا چقدر است؟

روی پروژه 10 هزار خطی، Ruff حدود 0.2 ثانیه و Flake8 حدود 6 ثانیه زمان می‌برد. این سرعت به‌دلیل Rust و کش هوشمند است و روی CI و pre-commit تفاوت را از «صبر آزاردهنده» به «لحظه‌ای» تبدیل می‌کند.

چطور فقط بعضی قوانین را فعال کنم؟

در [tool.ruff.lint] با select = ["E", "F", "I"] شروع کنید و سپس UP یا B را اضافه کنید. برای غیرفعال کردن خط خاص، از ignore = ["E501"] یا کامنت # noqa: E501 استفاده کنید.

آیا Ruff با Pylint هم جایگزین می‌شود؟

تا حدی. Ruff قوانین مهم Pylint را دارد اما تحلیل عمیق جریان داده Pylint را ندارد. اگر به تحلیل بسیار عمیق نیاز دارید، Pylint را کنار Ruff نگه دارید، وگرنه Ruff به‌تنهایی کافی و بسیار سریع‌تر است.

چطور Ruff را در CI اجرا کنم؟

در GitHub Actions دو قدم اضافه کنید: ruff check . و ruff format --check .. اگر خطا داد، CI قرمز می‌شود. نسخه را با astral-sh/setup-uv یا pip install ruff==0.8.4 پین کنید تا نوسان نسخه رخ ندهد.

آیا Ruff از Jupyter Notebook هم پشتیبانی می‌کند؟

بله از نسخه 0.1.8. با ruff check --fix notebook.ipynb و ruff format notebook.ipynb سلول‌ها را لینت و فرمت کنید. برای پروژه دیتا که نوت‌بوک زیاد دارد، همین قابلیت زمان تمیزکاری را نصف می‌کند.

جمع‌بندی

Ruff را با pip install ruff نصب و با ruff check --fix + ruff format اولین تمیزکاری را انجام دهید.
پیکربندی را در pyproject.toml با line-length = 88 و select = ["E","F","I","UP","B"] متمرکز کنید.
فرمت Black را حذف و فقط ruff format را استاندارد تیم کنید.
اتصال به VS Code (formatOnSave + fixAll) و pre-commit را فعال کنید تا تمیزی خودکار شود.
روی پایپ‌لاین AI و FastAPI، Ruff import، تایپ و کد منسوخ را خودکار درست می‌کند.
از امروز روی یک ریپو واقعی دو دستور ruff check --fix . و ruff format . را اجرا و نتیجه را کامیت کنید.

آموزش Ruff در پایتون؛ لینت و فرمت فوق‌سریع پروژه AI