ruff check --watch: Re-Lint on Change
ruff check --watch keeps Ruff running and re-lints automatically every time a watched file changes.
Watch mode is a developer convenience: edit a file, see violations update instantly. It is the opposite of a one-shot CI gate.
What it does
ruff check --watch runs the linter, then stays resident and re-runs whenever a relevant file changes on disk, printing the updated violations each time. It is interactive and long-running; it does not exit on its own.
Common usage
ruff check --watch .
ruff check --watch src
# watch a focused rule set while refactoring
ruff check --watch --select F .Flags
| Flag | What it does |
|---|---|
| --watch | Run continuously and re-lint on file changes |
| <paths> | Paths to watch and lint |
| --select <codes> | Restrict to chosen rules while watching |
| (not with --fix) | Watch is for reporting, not unattended fixing |
In CI
Never use --watch in CI: it never exits, so the job hangs until it times out. CI wants the one-shot ruff check . whose exit code gates the build. Watch mode is strictly for local development loops.
Common errors in CI
A pipeline step that hangs until the runner timeout is the signature of --watch left in a CI command; remove it and use a plain ruff check. On systems with low inotify limits, watch can warn it cannot watch all files; that is a local concern, not a CI one. Because watch is interactive, its exit code is not meaningful as a gate.