Supercharge Python Code Quality with Ruff: Lightning‑Fast Linting, Formatting, and CI Integration

Ruff is a high‑performance Python code checker and formatter written in Rust, designed to replace multiple tools such as Flake8, Black, isort, pyupgrade, and autoflake with a single, fast solution.

Installation and basic usage

Install Ruff with a single command:

# Recommended using uv
uv add ruff --dev
# Or with pip
pip install ruff

Run a quick lint on a sample file example.py: ruff check example.py The output identifies unused imports and variables, and indicates that two issues are automatically fixable.

example.py:3:8: F401 `os` imported but unused
example.py:4:8: F401 `sys` imported but unused
example.py:11:1: F841 Local variable `unused_var` is assigned to but never used
Found 3 errors.
[*] 2 fixable with the `--fix` option.

Apply automatic fixes: ruff check --fix example.py After fixing, the unused imports are removed and the file is cleaner.

Format the file with: ruff format example.py The formatter reports 1 file reformatted and enforces a consistent style.

Configuration

Ruff reads configuration from pyproject.toml, ruff.toml, or .ruff.toml. A typical pyproject.toml might look like:

[tool.ruff]
line-length = 88
target-version = "py310"

[tool.ruff.lint]
select = [
    "E",  # pycodestyle errors
    "W",  # pycodestyle warnings
    "F",  # Pyflakes checks
    "UP", # pyupgrade
    "B",  # flake8-bugbear
    "I",  # isort replacement
    "C4", # flake8-comprehensions
]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false

Per‑file or per‑directory overrides are supported:

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]
"**/__init__.py" = ["F401"]

Ruff can also import existing Black/isort configurations, making migration painless.

Editor integration

For VS Code, add the following to settings.json to use Ruff as the default formatter and enable auto‑fix on save:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.organizeImports": "always",
      "source.fixAll": "always"
    }
  }
}

Pre‑commit hook

Add Ruff to .pre-commit-config.yaml:

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

CI/CD integration

Example GitHub Actions workflow ( .github/workflows/lint.yml) runs Ruff linting and formatting on each push or pull request:

name: Lint & Format
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Ruff
        uses: astral-sh/ruff-action@v1
        with:
          args: "check --fix ."
      - name: Check Formatting
        run: ruff format --check .

These integrations ensure that only clean, well‑formatted code reaches the repository.

Conclusion

Ruff delivers four main benefits: extreme speed thanks to Rust, an all‑in‑one approach that replaces multiple tools, simple configuration that works out of the box, and seamless integration with modern development workflows (editors, Git, CI). It is a compelling upgrade for any Python project seeking faster and more maintainable code quality checks.