O que é Ruff

Ruff é uma ferramenta para analisar e formatar código Python. Ela encontra problemas estáticos, sugere correções e padroniza o estilo dos arquivos.

Criado pela Astral e escrito em Rust, o projeto reúne tarefas que costumavam ficar espalhadas entre linter, formatador e plugins.

A proposta é reduzir configuração e acelerar o retorno para o desenvolvedor, sem substituir testes ou revisão humana.

Como funciona

O Ruff lê os arquivos Python e aplica regras selecionadas no projeto. Assim, encontra imports não usados, problemas de estilo e padrões que merecem revisão sem executar a aplicação.

O comando ruff format reorganiza o código de forma determinística. O resultado pode ser conferido em um pull request.

A configuração costuma ficar no pyproject.toml, permitindo que a máquina local e o CI usem as mesmas decisões.

💡
Dica

Comece pelos arquivos novos para separar problemas antigos das alterações atuais.

Principais recursos

O lint identifica problemas e pode corrigir regras seguras com ruff check --fix.

O formatador integrado é executado com ruff format, seja em um arquivo ou no projeto inteiro.

Também é possível escolher regras, excluir diretórios e manter tudo em um arquivo de configuração versionado.

  • Lint para revisar código antes da execução.
  • Correções automáticas para regras compatíveis.
  • Formatação reproduzível para reduzir diferenças.

Como começar: instalação ou acesso

Instale o Ruff no ambiente virtual do projeto. O pacote pode ser instalado com pip, pipx ou uv, conforme o fluxo da equipe.

Com pip, execute:

Python -m pip install ruff
ruff check .
ruff format --check .

O segundo comando analisa os arquivos. O terceiro apenas verifica a formatação, sem modificar nada.

Para formatar, use ruff format .. Depois registre a configuração no pyproject.toml e repita os mesmos comandos no CI.

Exemplo prático

Uma configuração inicial pode selecionar erros comuns, imports e um alvo de Python:

[tool.ruff]
target-version = "py311"
line-length = 88

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]

[tool.ruff.format]
quote-style = "double"

Execute ruff check . para receber diagnósticos e ruff check . --fix para aplicar correções permitidas.

Antes do commit, use ruff format --check .. Se houver diferença, formate, revise o diff e só então confirme a alteração.

⚠️
Atenção

Correção automática não substitui revisão, especialmente em código legado ou com regras personalizadas.

Comparação com alternativas

Flake8 é uma opção tradicional de lint e possui muitos plugins. Black é conhecido por formatar Python com pouca configuração.

O Ruff pode concentrar parte dessas funções, mas a migração deve considerar plugins e convenções já adotados pelo repositório.

Em um projeto novo, a configuração concentrada é atraente. Em um projeto maduro, adote por etapas e compare os resultados no pipeline.

  • Escolha Ruff para integrar lint e formatação.
  • Mantenha plugins existentes quando eles forem parte do contrato do projeto.
  • Compare com Black quando a compatibilidade de estilo for essencial.

Pontos positivos e limitações

O ganho mais visível é operacional: menos ferramentas podem significar menos configuração e uma rotina de qualidade mais fácil de explicar.

A implementação em Rust favorece uma experiência rápida em muitos repositórios, embora o resultado dependa do projeto e do ambiente.

A limitação é que uma ferramenta única não reproduz automaticamente todos os plugins e decisões de uma cadeia antiga.

🔴
Cuidado

Faça a migração em uma branch, valide os testes e revise o diff antes de incorporar a mudança.

Casos de uso reais

Em uma API Python, o Ruff pode bloquear imports não usados antes dos testes e dar feedback rápido ao time.

Em um pacote open source, a formatação mantém pull requests menores e deixa a convenção documentada para contribuidores.

Em scripts de dados, o lint ajuda a encontrar variáveis esquecidas e trechos difíceis de manter, embora não valide a qualidade dos dados.

Em um monorepo, comece por diretórios novos e trate áreas legadas com uma exclusão temporária e documentada.

Dicas e boas práticas

Escolha as regras conscientemente. Ativar tudo no primeiro dia pode gerar ruído e esconder os avisos importantes.

🚀
Pro tip

Separe lint de formatação no pipeline para deixar claro o motivo de cada falha.

Use o modo de verificação no CI e deixe a alteração automática para a máquina local ou para uma etapa explícita.

Fixe a versão da ferramenta quando a reprodutibilidade for importante e atualize de forma planejada.

Mantenha os comandos no README ou no Makefile para que qualquer pessoa do time consiga executar a rotina.

Vale a pena?

O Ruff vale a pena para quem quer iniciar um projeto Python com lint e formatação integrados.

Ele não substitui testes, análise de tipos, ferramentas de segurança, revisão de arquitetura ou validação de regras de negócio.

O próximo passo é testar em uma branch, medir os avisos e levar ao CI apenas a configuração que o projeto consegue manter.