Ruff Professional Development

Overview

• Configuring and integrating Ruff into Python projects
• Understanding and fixing lint rule violations
• Formatting Python code with Ruff's formatter
• Setting up editor integrations
• Migrating from other Python tooling

Quick Start

Installation

references/installation.md

Basic Usage

ruff check .                    # Lint all files
ruff check path/to/file.py      # Lint specific file
ruff check --fix .              # Auto-fix violations

ruff format .                   # Format all files
ruff format path/to/file.py     # Format specific file
ruff format --check .           # Check formatting without changes

# pyproject.toml or ruff.toml
[tool.ruff]
line-length = 88
target-version = "py311"

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

references/configuration.md

Core Workflows

1. Integrating Ruff into a Project

1. Install Ruff (see

   references/installation.md

   )
2. Create initial configuration (see

   references/configuration.md

   )
3. Run initial check:

   ruff check .

4. Review and configure rules (see

   references/settings.md

   )
5. Set up pre-commit hooks or CI integration (see

   references/integrations.md

   )

2. Fixing Lint Violations

1. Run

   ruff check .

   to identify violations
2. For specific rule violations, reference

   references/rules/<rule-name>.md

3. Apply automatic fixes:

   ruff check --fix .

4. Manual fixes for remaining violations using rule documentation

• All 937 rules are in

  references/rules/

• Rules are named by their description (e.g.,

  unused-import.md

  ,

  line-too-long.md

  )
• See

  references/rules/rules.md

  for complete rule index

3. Code Formatting

1. Review formatter overview:

   references/formatter/overview.md

2. Configure formatter settings in

   pyproject.toml

3. Run formatter:

   ruff format .

4. For Black compatibility: see

   references/formatter/black.md

4. Editor Integration

1. Review

   references/editors/overview.md

   for editor support
2. Follow setup instructions:

   references/editors/setup.md

3. Configure editor settings:

   references/editors/settings.md

4. Explore editor features:

   references/editors/features.md

5. Migrating from Other Tools

• From Black: See

  references/formatter/black.md

• From Flake8/isort/pyupgrade: See

  references/configuration.md

  for rule equivalents
• General migration: See

  references/tutorial.md

  for migration guidance

Documentation Organization

references/INDEX.md

• configuration.md

  - Complete configuration reference

• settings.md

  - All available settings and options

• linter.md

  - Linter functionality and configuration

• tutorial.md

  - Comprehensive getting started guide

• formatter/overview.md

  - Formatter basics

• formatter/black.md

  - Black compatibility

• rules/rules.md

  - Rules overview and index

• rules/<rule-name>.md

  - Individual rule documentation

• editors/overview.md

  - Editor support overview

• editors/setup.md

  - Installation instructions

• editors/features.md

  - Available features

• editors/settings.md

  - Configuration options

• installation.md

  - Installation guide

• integrations.md

  - CI/CD and tool integrations

• versioning.md

  - Versioning and compatibility

• preview.md

  - Preview features

• faq.md

  - Frequently asked questions

• contributing.md

  - Contributing to Ruff

Finding Specific Information

1. Start with

   references/settings.md

   for all available options
2. Review

   references/configuration.md

   for configuration patterns
3. Check

   references/linter.md

   or

   references/formatter/overview.md

   for component-specific settings

1. Note the rule code/name from error message
2. Find corresponding file in

   references/rules/

3. Rules are alphabetically named (e.g., E501 →

   line-too-long.md

   )

1. Check

   references/editors/overview.md

   for supported editors
2. Follow

   references/editors/setup.md

   for your editor
3. Configure with

   references/editors/settings.md

1. Review

   references/tutorial.md

   for general guidance
2. See

   references/formatter/black.md

   for Black-specific migration
3. Check

   references/configuration.md

   for rule mapping from other linters

Included Scripts

scripts/

• scrape_ruff_docs.py - Scrape a single Ruff documentation page
• discover_ruff_docs.py - Discover all Ruff documentation URLs
• bulk_scrape_ruff.py - Bulk scrape all Ruff documentation

Best Practices

• Start with defaults and incrementally add rules
• Use

  select

  to enable rule categories,

  ignore

  for exceptions
• Test configuration changes incrementally
• Document reasoning for ignored rules in comments

• Review auto-fixes before committing
• Understand the rule before ignoring it
• Use inline ignores (

  # noqa

  ) sparingly
• Consider if the rule should be disabled project-wide

• Run formatter before linter to avoid conflicts
• Configure line length consistently across tools
• Use

  --check

  in CI to verify formatting
• Format entire codebase at once when first adopting

• Set up editor integration for immediate feedback
• Add pre-commit hooks for team consistency
• Include in CI pipeline with appropriate settings
• Document Ruff configuration in project README

Advanced Usage

• Use

  --cache-dir

  for faster repeated runs
• Configure file exclusions to skip irrelevant paths
• Leverage parallel execution (default behavior)

• See

  references/preview.md

  for experimental features
• Enable with

  preview = true

  in configuration
• Test preview rules before enabling in production

• Combine rule categories:

  select = ["E", "F", "I", "N"]

• Use per-file ignores for specific patterns
• Configure different rules for different directories

Documentation Coverage

• 937 individual rule documentation files
• Full configuration and settings reference
• Complete editor integration guides
• Formatter documentation including Black compatibility
• Installation, integration, and migration guides
• FAQ and troubleshooting resources