Python Linting with Ruff

Configure and use Ruff as the primary linter and formatter for Python projects. Ruff is an extremely fast Python linter and formatter written in Rust that replaces flake8, isort, pyupgrade, and many other tools.

When to Use This Skill

Setting up linting for new Python projects
Migrating from flake8/pylint/isort to Ruff
Configuring pyproject.toml for code quality
Fixing linting errors and warnings
Integrating linting into CI/CD pipelines

Standard Ruff Configuration

Add this configuration to pyproject.toml:

[tool.ruff]
line-length = 120
target-version = "py311"
lint.select = [
  "A",   # flake8-builtins
  "B",   # flake8-bugbear
  "C4",  # flake8-comprehensions
  "E",   # pycodestyle - errors
  "F",   # pyflakes
  "I",   # isort
  "RUF", # ruff specific rules
  "S",   # flake8-bandit (security)
  "UP",  # pyupgrade
  "W",   # pycodestyle - warnings
]
lint.ignore = ["S603", "A005"]
extend-exclude = ["src/generated/*"]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]  # Allow assert statements in tests

[tool.ruff.lint.isort]
known-first-party = ["orchestrator"]

Rule Categories Explained

Rule Set	Purpose	Examples
`A`	Prevents shadowing Python builtins	`id`, `list`, `type` as variable names
`B`	Catches likely bugs and design issues	Mutable default arguments, `except:` without type
`C4`	Improves comprehension usage	Unnecessary list() calls, better dict comprehensions
`E`	PEP 8 style errors	Line length, whitespace issues
`F`	Pyflakes errors	Undefined names, unused imports
`I`	Import sorting (isort replacement)	Alphabetical, grouped imports
`RUF`	Ruff-specific rules	Python-specific improvements
`S`	Security issues (bandit replacement)	Hardcoded passwords, SQL injection
`UP`	Python upgrade suggestions	Modern syntax, deprecated features
`W`	PEP 8 style warnings	Trailing whitespace, blank lines

Common Ignored Rules

Rule	Reason
`S603`	subprocess call without shell=True - often needed
`A005`	Module shadowing built-in - sometimes unavoidable
`S101`	Use of assert - allowed in tests only

Workflow Commands

Check for Issues

# Check all files
uv run ruff check src/

# Check specific file
uv run ruff check src/orchestrator/main.py

# Show all issues with explanations
uv run ruff check src/ --explain

Auto-fix Issues

# Fix auto-fixable issues
uv run ruff check src/ --fix

# Fix and show what changed
uv run ruff check src/ --fix --diff

# Fix unsafe fixes too (review changes!)
uv run ruff check src/ --fix --unsafe-fixes

Format Code

# Format all files
uv run ruff format src/

# Check formatting without changing
uv run ruff format src/ --check

# Show formatting diff
uv run ruff format src/ --diff

Integration with Other Tools

Pyright (Type Checking)

[tool.pyright]
reportMissingImports = true
reportMissingTypeStubs = false
pythonVersion = "3.12"
venvPath = "."
venv = ".venv"

Rope (Refactoring)

[tool.rope]
py_version = "3.10"
ignored_resources = [
    "*.pyc",
    "*~",
    ".ropeproject",
    ".hg",
    ".svn",
    "_svn",
    ".git",
    ".tox",
    ".venv",
    "venv",
    "node_modules",
]

Codespell (Spell Checking)

[tool.codespell]
count = true
quiet-level = 3
ignore-words-list = "basf,BASF,NotIn"
skip = "src/generated/**,package-lock.json,*.svg,CHANGELOG.md"

CI/CD Integration

GitHub Actions Workflow

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync
      - run: uv run ruff check src/
      - run: uv run ruff format src/ --check

Pre-commit Hook

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

Adding Ruff to a Project

Install Ruff as dev dependency
```
uv add ruff --dev
```
Add configuration to pyproject.toml (See Standard Ruff Configuration above)
Run initial check
```
uv run ruff check src/
```
Fix auto-fixable issues
```
uv run ruff check src/ --fix
```
Format code
```
uv run ruff format src/
```

Troubleshooting

Too Many Errors Initially

Start with fewer rules and add more over time:

[tool.ruff]
lint.select = ["E", "F", "I"]  # Start minimal

Conflicting with Black

Ruff format is compatible with Black. If using both, let Ruff format handle everything:

# Remove black, use ruff format
uv remove black

Import Sorting Issues

Configure first-party packages:

[tool.ruff.lint.isort]
known-first-party = ["orchestrator", "mypackage"]

python-linting-ruff