Guide · Open source
How to use Ruff: install, lint and format Python code
Updated · written with AI from the project's own documentation and checked against our catalogue data
Ruff is an extremely fast Python linter and code formatter written in Rust. It checks Python code for style problems and likely bugs, can format code, and can fix some errors automatically. This guide shows you how to install it, run its linter and formatter, and wire it into a pre-commit hook.
Ruffastral-sh/ruff · ★ 50.4k · MIT Install options & downloads Quick start
- 1Install Ruff. Install Ruff with uv (uv tool install ruff@latest), pip (pip install ruff) or pipx (pipx install ruff).
- 2Check your code. Run ruff check from your project folder to lint all Python files in it and its subfolders.
- 3Review the output. Read the reported rule violations and decide which ones to fix in your code.
- 4Fix what you can automatically. Use the fix option to let Ruff correct some errors, such as removing unused imports.
- 5Format your code. Run ruff format to apply consistent formatting across the files you choose.
- 6Automate it. Add Ruff to a pre-commit hook or your editor so checks run on every commit or save.
What Ruff does and what it replaces
Ruff is a single command-line tool. The README says it aims to replace several older Python tools, including Flake8, Black, and isort, and that it can also replace pydocstyle, pyupgrade and autoflake.
The README says Ruff is much faster than those tools, describing it as 10-100x faster than existing linters and formatters. Check the project's own documentation for detailed benchmarks.
- Linting: finds style problems and likely bugs in Python code
- Formatting: rewrites code into a consistent style
- Fixing: automatically corrects some errors, for example removing unused imports
- Configuration: supports pyproject.toml
Install Ruff with uv, pip or pipx
Ruff is available as ruff on PyPI. The README recommends installing it with uv, and also lists pip and pipx as options. The prerequisite listed is Python; the README excerpt does not state which Python version is required.
Pick one method. With uv, the README suggests installing globally as a tool. You can also add Ruff to a project as a development dependency.
# With uv.
uv tool install ruff@latest # Install Ruff globally.
uv add --dev ruff # Or add Ruff to your project.
# With pip.
pip install ruff
# With pipx.
pipx install ruffRun the linter with ruff check
Run ruff check to lint files. With no arguments it checks all files in the current directory and its subdirectories. You can also pass a folder, a set of files, or a text file containing newline-delimited arguments.
The README notes that Ruff has over 900 built-in rules, so the default output can be long on a large codebase.
- ruff check checks the current directory and subdirectories
- ruff check path/to/code/ checks one folder
- ruff check path/to/code/*.py checks all .py files in a folder
- ruff check path/to/code/to/file.py checks a single file
- ruff check @arguments.txt reads arguments from a file
ruff check # Lint all files in the current directory (and any subdirectories).
ruff check path/to/code/ # Lint all files in `/path/to/code` (and any subdirectories).
ruff check path/to/code/*.py # Lint all `.py` files in `/path/to/code`.
ruff check path/to/code/to/file.py # Lint `file.py`.
ruff check @arguments.txt # Lint using an input file, treating its contents as newline-delimited command-line arguments.Format code with ruff format
Use ruff format to format Python code. It accepts the same path forms as ruff check, so you can format the whole project or a single file.
- ruff format formats the current directory and subdirectories
- ruff format path/to/code/to/file.py formats a single file
ruff format # Format all files in the current directory (and any subdirectories).
ruff format path/to/code/ # Format all files in `/path/to/code` (and any subdirectories).
ruff format path/to/code/*.py # Format all `.py` files in `/path/to/code`.
ruff format path/to/code/to/file.py # Format `file.py`.Add Ruff as a pre-commit hook or editor integration
Ruff can run as a pre-commit hook through the ruff-pre-commit project. The example in the README runs the linter with the --fix argument and then runs the formatter. Set the rev value to the Ruff release you want, as shown in the project documentation.
Ruff also has a VS Code extension and supports various other editors. The README points to the editor setup documentation for details.
- The README example uses the hook ids ruff-check and ruff-format
- Editor integrations are listed in the project documentation
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: <ruff release tag>
hooks:
# Run the linter.
- id: ruff-check
args: [ --fix ]
# Run the formatter.
- id: ruff-formatConfigure Ruff with pyproject.toml
The README lists pyproject.toml support and hierarchical, cascading configuration for monorepos. Configuration details and the config file discovery rules are in the Ruff documentation, which is the place to check the exact settings.
What people use it for
- Replacing Flake8, Black and isort with one tool in a Python project
- Running fast checks across a large Python codebase
- Running linting and formatting automatically in a pre-commit hook
- Running checks on save inside an editor such as VS Code
Frequently asked questions
Is Ruff free to use?
Yes. The repository is licensed under the MIT licence, as the project's listing and README indicate. Check the LICENSE file in the repository for the full terms.
How do I install Ruff?
The README recommends uv (uv tool install ruff@latest). You can also use pip install ruff or pipx install ruff. Python is the listed prerequisite.
What Python version does Ruff need?
The README excerpt does not state the required Python version. Check the Ruff documentation or the PyPI page for the current requirement.
Does Ruff replace Flake8, Black and isort?
The README says Ruff can replace Flake8 (plus many of its plugins), Black, isort, pydocstyle, pyupgrade and autoflake. It also says it re-implements many popular Flake8 plugins, but not all of them, so check your plugins against its rules.
Can Ruff fix my code automatically?
Yes, for some errors. The README's example is removing unused imports. Ruff can't fix every rule, so review changes before committing.
Can I use Ruff for languages other than Python?
No. The project describes Ruff as a Python linter and formatter, so it only handles Python code.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Ruff suits Python developers and teams who want one fast tool for linting and formatting, especially on large codebases or in pre-commit hooks. Projects that depend on specific Flake8 plugins not covered by Ruff's rules, non-Python projects, or people who want a tool with few configuration choices should look at other options such as Flake8, Black, isort or pylint.
Install options & downloads