Ruff for Beginners: Lint and Format Python Code
Learn Ruff with a small Python project: find unused imports, preview fixes, format code, and add read-only checks without hiding useful warnings.
By Velloreth
Ruff gives a Python project two useful feedback loops: a linter that reports supported code problems and a formatter that makes layout consistent. Start with a tiny file, learn what each command changes, and only then apply it to a larger repository.
The aim is a repeatable check, not a wall of warnings. A beginner should be able to explain a reported problem, fix it, and run the same command again. This guide uses a disposable local folder and does not change an existing application.
Why this is a timely skill
The October 7, 2026 Talk Python tooling discussion describes a renewed focus on command-line tools, types, and checks around AI-assisted coding. That is a useful reason to learn a linter, not evidence that a particular search keyword is popular. Ruff’s own tutorial documents separate lint and formatting workflows. Neither source means every Python team must migrate.
For the broader packaging workflow, read the site’s uv introduction. This article stays focused on understanding diagnostics and safely applying formatting rather than repeating package-manager setup.
Create a small practice project
Use a supported Python installation and uv installed through its official instructions. If a workplace manages your machine, follow its installation policy. In a new folder, run:
uv init ruff-practice
cd ruff-practice
uv add --dev ruff
Save this as example.py:
import math
def greeting(name):
return "Hello, " + name
print(greeting("reader"))
The file deliberately imports math without using it. That is a small, understandable problem for a first lint check. It is better than starting with a large legacy repository and trying to interpret hundreds of unfamiliar findings at once.
Run the file before changing it:
uv run example.py
uv run ruff check example.py
The program prints a greeting. The linter should flag the unused import. These results are compatible: runnable code can still have a static problem. Conversely, a clean lint result does not guarantee correct output.
Read a diagnostic before fixing it
A useful diagnostic tells you which file and location to inspect, gives a rule identifier, and describes the problem. Read the relevant source line. Ask whether the import is truly unused or whether the example is incomplete. For this file, removing import math is the intended change.
First remove it manually and rerun the check. That teaches the connection between the message and the code. You can then reintroduce the line to try the automatic fix workflow:
uv run ruff check --fix example.py
Inspect the file afterward. In a real Git repository, use git diff before committing. Automatic changes should still have a human-readable explanation. If a tool proposes a large rewrite, narrow the command to one file and understand that smaller diff first.
Do not add blanket ignore comments simply to make the terminal green. A deliberate exception can be reasonable, but it should name the relevant rule and have a clear reason. Otherwise the warning has disappeared without the underlying question being answered.
Keep formatting separate from linting
Now deliberately make the spacing uneven:
def greeting( name ):
return "Hello, " + name
Check formatting without writing changes:
uv run ruff format --check example.py
Apply formatting when you are ready:
uv run ruff format example.py
Then rerun both checks. The distinction matters in automation: a read-only gate should report a problem rather than silently rewrite the files that someone is reviewing.
| Goal | Command |
|---|---|
| Find supported lint problems | uv run ruff check . |
| Apply supported automatic fixes | uv run ruff check --fix . |
| Check layout without writing | uv run ruff format --check . |
| Apply the formatter | uv run ruff format . |
A formatter chooses a consistent representation. It does not choose good variable names, correct a business rule, or decide whether an algorithm is appropriate. Those still need reading and tests.
Add configuration only when there is a reason
Ruff supports project configuration in pyproject.toml. A small formatting preference can look like this:
[tool.ruff]
line-length = 88
Avoid copying a huge configuration from a different codebase. Rule defaults and available settings can change across releases. Check the documentation for the installed version before copying an old tutorial’s list. If a team already has a formatter, agree on a migration rather than running competing formatters over the same files.
Keep formatting-only changes separate from behavior changes when practical. A reviewer can then see whether a bug fix actually changed logic instead of searching through unrelated whitespace. The site’s code review checklist explains why small, focused diffs are easier to verify.
Make the check useful in daily work
Before a commit, run the linter, the read-only formatter check, and the project’s tests. Run those same commands in automation after checking out the intended revision and installing the declared development dependencies. A linter installed globally at a different version can produce a different result from the project environment.
If the check fails, read the first relevant message rather than changing every setting. Confirm the working directory, the file being checked, and whether the dependency is available in that environment. For an older project, introduce the tool in a small area first and record the agreed scope.
The static analysis overview explains the wider category. Ruff is one part of that category. Tests cover behavior, type checkers inspect type relationships, and runtime validation checks incoming data. None is a substitute for all the others.
A short completion checklist
You are ready to move beyond the practice file when you can explain the unused-import warning, run a check without editing files, inspect an automatic fix, and distinguish formatting from correctness. Keep the configuration short enough to explain. Treat every new rule as a project decision rather than a score to maximize.
Sources and scope
Checked October 26, 2026. Commands follow the official Ruff tutorial. The timely tooling context comes from Talk Python’s October 2026 discussion. This is a practical tutorial, not a speed benchmark or a claim of measured search demand.