# Step 1: Format the code
uv run ruff format .

# Step 2: Fix auto-fixable linting issues
uv run ruff check --fix .

# Step 3: Report remaining issues
uv run ruff check .

Project Commands

just fmt-python    # Format Python code
just lint-python   # Lint Python code

Quick Reference

Commands

Command	Purpose
`uv run ruff check .`	Lint code
`uv run ruff check --fix .`	Fix auto-fixable issues
`uv run ruff format .`	Format code
`uv run ruff format --check .`	Check formatting
`uv run ruff check --diff .`	Preview fixes

Common Flags

Flag	Effect
`--fix`	Auto-fix issues
`--unsafe-fixes`	Apply risky fixes
`--diff`	Show changes without applying
`--select E,F`	Check specific rules
`--ignore E501`	Skip specific rules
`--statistics`	Show issue counts
`--watch`	Continuous linting

Linting Workflow

1. Check for Issues

uv run ruff check .                    # All files
uv run ruff check src/                 # Directory
uv run ruff check script.py            # Single file

2. Auto-fix Safe Issues

uv run ruff check --fix .

3. Review Unsafe Fixes

uv run ruff check --diff --unsafe-fixes .   # Preview
uv run ruff check --fix --unsafe-fixes .    # Apply

4. Address Remaining Issues

Fix manually or suppress with # noqa:

import unused_module  # noqa: F401

Formatting Workflow

1. Format Code

uv run ruff format .

2. Check Without Modifying (CI/CD)

uv run ruff format --check .

3. Preview Changes

uv run ruff format --diff .

Rule Selection

Essential Rules (Start Here)

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

Prefix	Source	Purpose
F	Pyflakes	Errors, undefined names
E	pycodestyle	PEP 8 errors
I	isort	Import sorting

Recommended Rules

[tool.ruff]
select = ["F", "E", "I", "W", "UP", "B", "SIM"]

Prefix	Source	Purpose
W	pycodestyle	PEP 8 warnings
UP	pyupgrade	Modernize syntax
B	bugbear	Likely bugs
SIM	simplify	Simplification

Security Rules

[tool.ruff]
extend-select = ["S"]

Project Configuration

Basic pyproject.toml

[tool.ruff]
line-length = 100
target-version = "py311"

select = ["E", "F", "I", "B", "UP"]
ignore = ["E501"]

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

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

Per-file Ignores

Pattern	Common Ignores	Reason
`tests/*/.py`	S101	Allow assert
`__init__.py`	F401	Allow unused imports
`scripts/*.py`	T201	Allow print

Inline Suppression

# Ignore all rules for line
import os  # noqa

# Ignore specific rule
import os  # noqa: F401

# Ignore for entire file (at top)
# ruff: noqa: F401

Troubleshooting

Too Many Issues

Start with essential rules only:
```
uv run ruff check --select=F,E .
```
Add noqa comments to existing violations:
```
uv run ruff check --add-noqa .
```
Fix auto-fixable issues first:
```
uv run ruff check --fix .
```
Enable rules gradually over time

Configuration Not Loading

Check file names: ruff.toml, .ruff.toml, or pyproject.toml
Validate syntax: uv run ruff check --config=ruff.toml .
Check for conflicts in parent directories

Formatter vs Linter Conflicts

Run formatter before linter to avoid conflicts:

uv run ruff format .
uv run ruff check --fix .

Output Formats for CI

uv run ruff check --output-format=github .   # GitHub Actions
uv run ruff check --output-format=gitlab .   # GitLab CI
uv run ruff check --output-format=json .     # JSON

References

Project References

Rules Reference - Complete rule descriptions by category
Configuration Reference - Config templates and options

External Resources

Best Practices

Format first - Run ruff format before ruff check
Use --fix liberally - Most auto-fixes are safe
Review unsafe fixes - Always check --unsafe-fixes changes
Start simple - Begin with F, E, I rules; expand gradually
Configure CI/CD - Enforce checks in continuous integration
Document exceptions - Comment why rules are disabled

ruff

Ruff Skill

Contents

Proactive Usage

Standard Workflow