astral-sh/ruff-action

Lint or format-check Python with Ruff, auto-resolving the version from pyproject.toml.

Official actionCategory: Code Quality & LintingLatest v4View on GitHub

What it does

astral-sh/ruff-action is the official action for Ruff, the fast Python linter and formatter. By default it runs ruff check over the workspace.

The Ruff version is resolved from pyproject.toml (searched upward from src), a version-file, or an explicit version input, falling back to latest, so CI matches the version your project pins.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
  - uses: astral-sh/ruff-action@v4          # ruff check (default)
  - uses: astral-sh/ruff-action@v4
    with:
      args: format --check

Inputs

Input	Description	Default	Required
`args`	Arguments passed to Ruff. Defaults to `check`.	`check`	No
`src`	Source path(s) or glob pattern(s) to run Ruff on. Defaults to the current workspace.	`${{ github.workspace }}`	No
`version`	The version of Ruff to use, e.g. `0.6.0`. Defaults to the first discoverable version in pyproject.toml, or `latest`.	-	No
`version-file`	Path to a pyproject.toml, requirements.txt or uv.lock file to read the version from.	-	No
`github-token`	Used for authenticated downloads of Ruff release artifacts from GitHub.	`${{ github.token }}`	No

Outputs

Output	Description
`ruff-version`	The installed ruff version. Useful when using latest.

Notes

In CI use args: format --check, plain format rewrites files on the runner and exits 0, so the job passes without telling you anything.

Pin the Ruff version in pyproject.toml (or the version input) so lint results are reproducible; unpinned latest can start failing when a new Ruff release adds rules.

Common errors

GitHub API rate-limit failures while downloading Ruff happen when the mirror is disabled and the token is missing; keep download-from-astral-mirror on (default) or pass github-token.
A run that passes in CI but fails locally (or vice versa) usually means different Ruff versions, check the ruff-version output against your local ruff --version and pin the version.

Security and pinning

Pin the action to a commit SHA and pin the Ruff version, the action downloads and executes a release binary as part of the job.

Alternatives and related

actions/setup-pythonInstall a specific Python version and cache pip, pipenv, or poetry dependencies. pre-commit/actionRun your repo's pre-commit hooks in CI, with the hook environments cached. super-linter/super-linterOne Docker action that runs a whole collection of linters across every language in the repo.

Frequently asked questions

Which Ruff version does the action install?

By default it reads the version pinned in pyproject.toml (searched upward from src), or a version-file like uv.lock; if nothing is found it uses the latest release. The resolved version is exposed as the ruff-version output.