Getting started

Install

simplint ships as a single binary inside a Python wheel, like Ruff, so it needs no Python at runtime. Install it as a tool with uv or pipx, which keeps it apart from the project it lints.

uv tool install simplint
simplint --help

python -m pip install pipx-in-pipx --user
pipx install simplint
simplint --help

python -m pip install --user simplint
simplint --help

Note

A user installation shares the interpreter’s package set. Prefer uv or pipx when an operating system or package manager owns that interpreter.

Check a project

Run simplint from the project root:

simplint check .

Important

Check the whole project, tests included. Several rules need to know which names other modules import.

simplint check works like ruff check:

  • It finds the same files and honors the same exclude settings and .gitignore.

  • It lints every .py file under the paths you give it, the current directory by default. - reads one file from standard input.

  • It prints in the same formats. By default each report shows the offending code, as ruff check does. --output-format concise prints one line per report, and [*] marks a report with a safe fix.

  • It exits the same way: status 1 while any report remains, and status 2 when it cannot run, such as on invalid configuration.

Read a report

Each report names the file, the line and column, the rule and what to change. This is one report from the run on the home page, in the concise format:

src/tox/util/path.py:16:1: SMP601 `_CACHEDIR_TAG` is never reassigned; annotate it `Final`

The rule’s page in the rules reference explains the check and its fix.

Apply the safe fixes

To apply the safe fixes, add --fix. Run simplint between Ruff’s linter and its formatter:

ruff check --fix .
simplint check --fix .
ruff format .

One round is final: running the three again changes nothing. simplint leaves layout to ruff format, so its output need not be formatted, only something one ruff format run finishes.

A simplint fix can give one of the project’s Ruff rules something to report that the file was clean for. simplint then makes sure ruff check has no new work:

no

yes

yes

no

simplint fix

New Ruff report?

Keep the fix

Ruff has a fix?

Apply Ruff's fix too

Withdraw the fix,
keep the report

ruff format

An import a fix leaves unused is the typical case: Ruff’s own fix removes it.

Turn a rule off

Every rule runs by default. To turn one off, list it in the [tool.simplint] table of pyproject.toml. This example turns off missing-final, the rule behind the Final report above:

[tool.simplint]
ignore = ["missing-final"]

Run simplint check . again. The reports of that rule are gone, and the others stay.

Next steps