A Surprising Secret About Python Linters

Why You Might Need to Run Your Linter Twice

It sounds a little ridiculous at first: you run your linter, fix the issues, run it again… and suddenly it finds more issues. Wait, what?

Yes, it’s a real thing. Depending on the complexity of your code and the tools you’re using, sometimes one pass isn’t enough to get a clean bill of health. But don’t worry; there’s a simple explanation… and a better way to handle it.

Linters hate this one weird trick: you should run them twice!

Why One Pass Isn’t Enough

Let’s talk about Python, and three great tools for writing clean, idiomatic code: isort, black, and ruff. These are the linters and formatters we recommend, and the ones Caparra supports out of the box.

• isort handles import sorting: standard library, third-party, local imports, all in the right order.

• black is an uncompromising formatter: it rewrites your code into a consistent, readable style.

• ruff is a lightning-fast linter that enforces style rules and flags bugs across dozens of common Python checks.

They work well together, but here’s the kicker: they don’t always finish the job in one pass. For example, ruff might flag an unused import, which you remove… but that shifts the ordering of your imports, which triggers isort. Or black rewrites a function signature in a way that introduces a new ruff warning.

So you fix the first round of issues, run the linters again… and boom, new problems. That’s not your fault. It’s just how these tools interact.

Multi-Pass Linting is a Best Practice

We’ve seen this pattern enough to make it a rule: run your linters more than once. Run, fix, run again. Keep going until the output is clean.

You can wire this up yourself with a shell script or task runner. Some teams use pre-commit to sequence these tools and repeat them until the exit codes go green. But that takes setup, maintenance, and discipline across the whole team.

That’s why Caparra automates it for you.

Caparra Gets to Clean, Automatically

When the Caparra team was building our GitHub app, all of this nearly drove us nuts. We are building AI-powered tools that automate repetitive DevOps tasks—like running linters and formatters.

When we tell you that our tools do a job for you, we can't accept getting your code only halfway clean. That's why our GitHub app chains isort, black, and ruff together in the right order, understands their output, and runs them as many times as needed to get clean.

No more flaky CI runs because a file wasn’t formatted exactly right. No more waiting for a human to notice that a "fix" caused new issues. The Caparra Agent handles it, and keeps your codebase polished and consistent.

It’s a simple example of what we mean by brilliance in the basics, a phrase we borrowed from our Marine Corps days. High-performing teams don’t cut corners on fundamentals.

If you want a reliable way to run isort, black, and ruff without getting tangled in tool output or CI failures, open a free Caparra account. You’ll get access to our Agent, early product features, and a great way to offload the small-but-essential tasks that keep your code healthy.

Let your team focus on what really matters. We’ll take care of the linters.