Guide complet de Ruff : réécrire la vérification du code Python en Rust, 100 fois plus rapide que Flake8

TL;DR : Ruff est un outil de vérification de code Python écrit en Rust (linter + formatter), 10 à 100 fois plus rapide que Flake8. Il peut analyser un projet massif de 300 000 lignes de code en 0,5 seconde. En 2026, Ruff est devenu l'outil de facto pour la qualité du code dans l'écosystème Python, adopté par des projets célèbres comme Instagram, PyTorch, Jupyter et Apache Airflow. Ce guide vous accompagne de zéro dans l'utilisation de Ruff : installation, configuration et guide de migration complet pour remplacer Flake8/Black/isort.

1. Qu'est-ce que Ruff ?

Ruff est développé par l'équipe Astral (la même équipe derrière uv) et écrit en Rust. Il se positionne comme un outil de vérification de code tout-en-un pour l'écosystème Python. Il intègre les fonctionnalités de plusieurs outils indépendants :

Pourquoi Ruff est-il si rapide ?

1. Compilation Rust : les performances de Rust dépassent largement Python, la vitesse d'analyse présente un ordre de grandeur de différence
2. Traitement parallèle : utilise automatiquement les cœurs multiples du CPU pour analyser les fichiers en parallèle
3. Zéro dépendance : aucun runtime Python nécessaire, un seul binaire suffit
4. Cache incrémental : seuls les fichiers modifiés sont vérifiés, la deuxième exécution est quasi instantanée

Le dépôt GitHub de Ruff : https://github.com/astral-sh/ruff ⭐ Il dépasse les 35 000 étoiles en 2026.

2. Installer Ruff

Ruff supporte plusieurs méthodes d'installation. La recommandation est d'utiliser pip ou le script d'installation officiel :

# Méthode 1 : via pip (recommandé)
pip install ruff

# Méthode 2 : via uv (plus rapide)
uv tool install ruff

# Méthode 3 : macOS Homebrew
brew install ruff

# Méthode 4 : script d'installation officiel
curl -LsSf https://astral.sh/ruff/install.sh | sh

# Vérifier l'installation
ruff --version
# Résultat : ruff 0.9.x

Après l'installation, Ruff propose deux commandes principales :

• ruff check : vérification du code (mode linter)
• ruff format : formatage du code (mode formatter)

3. Prise en main rapide : vérifiez votre projet en 5 minutes

Créez un fichier de test hello.py :

import os
import sys
import json  # unused

def  hello_world():
    x=1+2
    print("hello world")
    return x

if __name__ == "__main__":
    hello_world()

3.1 Exécuter la vérification du code

ruff check hello.py

Exemple de sortie :

hello.py:1:8: F401 [*] `os` imported but unused
hello.py:2:8: F401 [*] `sys` imported but unused
hello.py:3:8: F401 [*] `json` imported but unused
hello.py:5:1: W293 [*] Blank line contains whitespace
hello.py:7:6: E225 [*] Missing whitespace around operator
Found 5 errors.
[*] 5 fixable with the `--fix` option.

Ruff a identifié avec précision 5 problèmes : 3 imports inutilisés, 1 ligne vide superflue et 1 espace manquant autour d'un opérateur. Chaque erreur indique si elle peut être corrigée automatiquement avec --fix.

3.2 Correction automatique

ruff check --fix hello.py

Après exécution, le fichier est automatiquement corrigé :

def hello_world():
    x = 1 + 2
    print("hello world")
    return x

if __name__ == "__main__":
    hello_world()

3.3 Formatage du code

ruff format hello.py

ruff format fonctionne comme Black : il ajuste automatiquement l'indentation, les lignes vides, le style de guillemets, etc., pour garantir un style de code uniforme dans tout le projet.

4. Configuration détaillée

Créez un fichier pyproject.toml à la racine du projet pour configurer Ruff :

[tool.ruff]
# Version Python cible
target-version = "py312"
# Limite de longueur de ligne
line-length = 88
# Répertoires à vérifier
src = ["src", "tests"]
# Répertoires exclus
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# Ensembles de règles activés
select = [
    "E",      # erreurs pycodestyle
    "W",      # avertissements pycodestyle
    "F",      # pyflakes
    "I",      # isort (tri des imports)
    "UP",     # pyupgrade (suggestions de mise à jour de version)
    "B",      # flake8-bugbear (patterns de bugs courants)
    "SIM",    # flake8-simplify (simplification du code)
    "RUF",    # règles propres à Ruff
]
# Règles ignorées
ignore = [
    "E501",   # ligne trop longue (géré par le formatter)
    "E402",   # import pas en haut du fichier (nécessaire pour certains scripts)
]
# Complexité maximale autorisée
mccabe.max-complexity = 10

[tool.ruff.lint.per-file-ignores]
# Ignorer certaines règles pour les fichiers de test
"tests/**/*.py" = ["S101", "PLR2004"]
# Ignorer toutes les règles pour les fichiers de migration
"**/migrations/*.py" = ["ALL"]

[tool.ruff.format]
# Style de guillemets : simples ou doubles
quote-style = "double"
# Type d'indentation
indent-style = "space"
# Saut de ligne final
skip-magic-trailing-comma = false

4.1 Description des ensembles de règles courants

5. Guide de migration complet : remplacer Black/isort/Flake8

Si votre projet utilisait auparavant la combinaison Black + isort + Flake8, vous pouvez migrer entièrement vers Ruff.

5.1 Désinstaller les anciens outils

pip uninstall black isort flake8 autoflake pyupgrade -y

5.2 Configurer Ruff pour une compatibilité comportementale

Ajoutez dans pyproject.toml une configuration compatible avec Black :

[tool.ruff]
line-length = 88          # largeur de ligne par défaut de Black
target-version = "py312"

[tool.ruff.format]
quote-style = "double"    # guillemets doubles par défaut de Black
indent-style = "space"

[tool.ruff.lint]
select = ["E", "W", "F", "I"]

5.3 Corriger l'ensemble du projet en lot

# Étape 1 : formater tous les fichiers Python
ruff format .

# Étape 2 : vérifier et corriger automatiquement
ruff check --fix .

# Étape 3 : afficher les problèmes restants (sans correction automatique)
ruff check .

5.4 Intégration avec pre-commit

Créez un fichier .pre-commit-config.yaml :

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      # Formater d'abord
      - id: ruff-format
      # Vérifier ensuite
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

Installez le hook pre-commit :

pip install pre-commit
pre-commit install

Désormais, à chaque git commit, Ruff formate et vérifie automatiquement les fichiers indexés.

6. Intégration CI/CD en pratique

6.1 GitHub Actions

name: Ruff Check

on: [push, pull_request]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Ruff
        run: pip install ruff

      - name: Run Ruff format check
        run: ruff format --check .

      - name: Run Ruff lint
        run: ruff check --output-format=github .

6.2 GitLab CI

ruff:
  image: python:3.12-slim
  stage: test
  script:
    - pip install ruff
    - ruff format --check .
    - ruff check .
  allow_failure: true  # peut être autorisé à échouer au départ

6.3 Optimiser les performances pour les projets de grande taille

Pour les projets massifs, voici quelques stratégies d'optimisation :

# Vérifier uniquement les fichiers modifiés (scénario CI)
ruff check --diff .

# Sortie au format SARIF (pour GitHub Code Scanning)
ruff check --output-format=sarif . > results.sarif

# Vérifier uniquement certaines règles
ruff check --select=F,E .

# Afficher l'état de la configuration et du cache de Ruff
ruff check --show-settings .

7. Comparaison avec les concurrents

Test de performance en conditions réelles

Sur un projet de 500 000 lignes de code :

• Ruff check : 0,3 seconde
• Flake8 : 45 secondes
• pylint : 120 secondes

Ruff est environ 150 fois plus rapide que Flake8 et 400 fois plus rapide que pylint.

8. Utilisation avancée

8.1 Règles personnalisées

Ruff permet de personnaliser la sévérité des règles via pyproject.toml :

[tool.ruff.lint]
select = ["E", "F", "W"]

# Certaines règles peuvent être classées comme avertissement plutôt qu'erreur
[tool.ruff.lint.flake8-errmsg]
max-string-length = 20

[tool.ruff.lint.pydocstyle]
convention = "google"  # ou "numpy", "pep257"

8.2 Intégration avec l'IDE

VS Code : installez l'extension officielle Ruff, qui offre : - vérification lint en temps réel - formatage automatique à la sauvegarde - correction des suggestions en un clic

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

PyCharm : configuration via External Tools : - Ouvrez Settings → Tools → External Tools - Ajoutez Ruff : Program = ruff, Arguments = check --fix $FilePath$

8.3 Vérification incrémentale (mode Watch)

# Surveiller les modifications de fichiers et revérifier automatiquement
ruff check --watch .

8.4 Générer un rapport HTML

# Sortie au format JSON, traitable avec jq
ruff check --output-format=json . | jq '.'

# ou format sarif pour GitHub Code Scanning
ruff check --output-format=sarif . > ruff-results.sarif

9. Questions fréquentes

Q1 : Ruff peut-il remplacer complètement Flake8 ?

Dans la plupart des cas, oui. Ruff intègre la plupart des règles de Flake8 (séries E, W, F), ainsi que les règles de certains plugins populaires (bugbear, eradicate, etc.). Mais si vous utilisez des plugins Flake8 très niche, vous devrez vérifier que Ruff dispose d'une implémentation équivalente.

Q2 : Ruff peut-il remplacer pylint ?

Pas entièrement. Ruff se concentre sur le style du code et la détection de bugs courants, tandis que pylint propose une analyse plus approfondie de la qualité du code (évaluation de complexité, détection de code dupliqué, etc.). Pour le développement quotidien, Ruff suffit largement. Pour un audit qualité strict, on peut combiner Ruff et pylint.

Q3 : --fix de Ruff est-il sûr ?

Très sûr. La correction automatique de Ruff ne s'applique qu'aux règles disposant d'une stratégie de correction claire, sans toucher à la sémantique du code. Il est conseillé de prévisualiser les modifications avec ruff check --diff . avant de les appliquer.

Q4 : quelles versions de Python Ruff supporte-t-il ?

Ruff lui-même supporte la vérification de code pour Python 3.7 à 3.13. Via la configuration target-version, vous pouvez spécifier la version Python cible et obtenir des suggestions de mise à jour correspondantes.

10. Conclusion

Ruff est en train de devenir l'infrastructure de qualité du code dans l'écosystème Python. Grâce à des performances extrêmes apportées par Rust, un riche ensemble de règles intégrées et une expérience unifiée linter + formatter, Ruff rend la gestion de la qualité du code dans les projets Python plus simple et efficace que jamais.

Recommandations d'action :

1. Installez avec pip install ruff
2. Exécutez ruff check --fix . + ruff format . dans votre projet
3. Configurez pyproject.toml pour personnaliser les règles
4. Intégrez dans le pipeline pre-commit et CI/CD

La qualité du code de votre projet s'améliorera considérablement en quelques minutes seulement.

Liens utiles :

• Documentation officielle Ruff : https://docs.astral.sh/ruff/
• Ruff GitHub : https://github.com/astral-sh/ruff
• Outil uv (même équipe que Ruff) : https://docs.astral.sh/uv/
• Ressource connexe : linux-tutorials/linux-fileformat.md — Comprendre les formats de fichiers Python
• Ressource connexe : linux-tutorials/ubuntu-dependency.md — Gestion des paquets Python