O que é o Ruff

O Ruff e um linter e formatador de código Python extremamente rápido, escrito em Rust. Foi criado pela Astral, empresa fundada por Charlie Marsh, e lançado em 2022. Em poucos anos se tornou uma das ferramentas mais adotadas no ecossistema Python por ser dezenas de vezes mais rápido que as alternativas tradicionais como Flake8, pylint e Black combinados.

A versão 0.16.0, lançada recentemente, trouxe uma mudança significativa: o número de regras ativadas por padrão saltou de 59 para 413. Isso significa que ao instalar o Ruff e rodar sem nenhuma configuração, você já recebe uma análise muito mais completa do seu código, detectando muito mais problemas automaticamente.

O post de lançamento foi destaque no Hacker News com mais de 77 pontos, com desenvolvedores discutindo as implicações de ter mais de 400 regras ativas por padrão e como isso impacta projetos existentes.

Como funciona

O Ruff e um binário único escrito em Rust que analisa código Python. Por ser compilado, não tem o overhead de inicializar o interpretador Python a cada execução, o que explica grande parte da sua velocidade. Em benchmarks, o Ruff analisa codebases de centenas de milhares de linhas em menos de um segundo.

Internamente, o Ruff implementa um parser de Python próprio e aplica as regras de análise estática diretamente sobre a AST (Abstract Syntax Tree) do código. Cada regra verifica um padrão específico: variáveis não usadas, imports mal ordenados, comparações problemáticas, tipos de dados incorretos e centenas de outros padoes.

Com o Ruff 0.16.0, a expansão de 59 para 413 regras padrão foi feita de forma cuidadosa: as regras novas foram selecionadas por terem baixa taxa de falsos positivos e alta utilidade prática. A equipe da Astral rodou as novas regras em milhares de projetos open source antes de ativar por padrão.

💡
Dica

O Ruff tem mais de 800 regras implementadas no total. A diferença entre o que existe e o que é ativado por padrão e proposital: as regras mais opinativas ou com maior risco de falso positivo ficam desativadas até você optar por elas explicitamente.

Principais mudanças no Ruff 0.16.0

A expansão de 59 para 413 regras padrão e a mudança mais visível, mas o 0.16.0 trouxe outras melhorias relevantes:

  • 413 regras padrão: Cobertura muito mais ampla sem configuração adicional. Projetos novos se beneficiam imediatamente.
  • Novas categorias ativadas: Regras de pycodestyle (E/W), pyflakes (F), pep8-naming (N), flake8-bugbear (B) e isort (I) agora todas ativas por padrão.
  • Melhorias no formatador: Compatibilidade melhorada com o formato do Black para projetos migrando do Black para o Ruff.
  • Novas correções automáticas: Mais regras agora tem a opcao --fix para corrigir automaticamente sem intervenção manual.
  • Desempenho: Melhorias adicionais de performance no parser, especialmente em codebases grandes.
⚠️
Atenção

Se você já usa Ruff em produção com CI/CD, atualizar para 0.16.0 sem revisar as novas regras pode quebrar o pipeline. Teste primeiro em um branch separado e ajuste o pyproject.toml para ignorar regras que não fazem sentido para o seu projeto.

Como começar: instalação e configuração

O Ruff e instalado via pip ou uv. Para projetos novos, a recomendação e instalar como dependência de desenvolvimento:

# Instalar o Ruff
pip install ruff

# Ou com uv (mais rápido)
uv add --dev ruff

# Verificar a instalação
ruff --version

# Rodar no projeto inteiro
ruff check .

# Formatar o código (equivalente ao Black)
ruff format .

# Corrigir automaticamente o que for possível
ruff check --fix .

Para configurar no pyproject.toml:

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

[tool.ruff.lint]
select = ["E", "F", "I", "B", "N"]
ignore = ["E501"]  # ignorar linha longa se necessário

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

Exemplo prático: antes e depois

Com 413 regras ativas por padrão, o Ruff 0.16.0 detecta muito mais problemas em código existente. Exemplo de código com vários problemas que o Ruff agora encontra automaticamente:

# Código com problemas (detectados pelo Ruff 0.16.0)
import os
import sys
import os  # duplicado

def calcular(x,y):  # falta espaço após virgula
    resultado = x+y  # falta espaços ao redor do operador
    return resultado

if x == None:  # E711: comparação com None deve usar 'is'
    pass

# Rodar: ruff check arquivo.py
# Resultado: 4 erros encontrados, 3 com correção automática disponível
🚀
Pro tip

Use ruff check --statistics para ver quais regras estão gerando mais erros no seu projeto. Isso ajuda a priorizar o que corrigir primeiro e a entender quais padrões são mais comuns no seu codebase.

Comparação com alternativas

Antes do Ruff, o fluxo padrão era usar Flake8 para lint + Black para formatação + isort para imports. Cada ferramenta com sua própria configuração e seu próprio tempo de execução. O Ruff substitui todos os três com uma única ferramenta.

  • Flake8 + plugins: Lento, ecossistema de plugins fragmentado, configuração espalhada. Ruff e 10-100x mais rápido.
  • pylint: Mais regras mas muito mais lento e com mais falsos positivos. Ruff e mais opinativo e rápido.
  • Black: Só formata, não faz lint. Ruff formata e linteia com compatibilidade de formato com o Black.
  • mypy: Verificação de tipos estáticos, diferente de lint. Ruff não substitui o mypy, os dois se complementam.

Pontos positivos e limitações

Os pontos positivos são claros: velocidade excepcional, uma só ferramenta para lint e formatação, zero configuração para começar e suporte ativo com atualizações frequentes. A integração com VSCode, PyCharm e outros editores e excelente.

As limitações existem. O Ruff não faz verificação de tipos, então mypy ou pyright continuam necessários para projetos que precisam de type safety. Algumas regras muito específicas do pylint não tem equivalente no Ruff ainda.

Com 413 regras ativas por padrão no 0.16.0, projetos existentes que atualizam sem revisar podem ter surpresas desagradáveis no CI. A migração exige um momento de ajuste para desativar regras que não fazem sentido para o contexto do projeto.

🔴
Cuidado

Nunca rode ruff check --fix em um codebase grande pela primeira vez sem antes revisar as mudanças. Algumas correções automáticas, especialmente em imports e formatação de strings, podem introduzir comportamentos inesperados em código legado.

Casos de uso reais

O Ruff se encaixa bem em vários perfis de projeto:

  • Projeto Python novo: Instale o Ruff desde o inicio, ative as 413 regras padrão e mantenha o código limpo desde o primeiro commit.
  • Time que usa Flake8 + Black: Migração gradual e possível. O Ruff aceita a maioria das configurações do Flake8 e formata de forma compatível com o Black.
  • Pipeline de CI lento: Substituir Flake8 e Black pelo Ruff pode reduzir o tempo de lint e formatação de minutos para segundos em projetos grandes.
  • Projeto open source grande: O Ruff e usado por FastAPI, pandas, Django, Hugging Face e dezenas de projetos grandes. E uma escolha segura e bem suportada.

Dicas e boas práticas

💡
Dica

Configure o Ruff como pre-commit hook para garantir que nenhum código fora do padrão entre no repositório. Use o pacote pre-commit com a integração oficial do Ruff disponível no repositório oficial.

💡
Dica

Para projetos legados com muitos erros, use ruff check --add-noqa para adicionar comentários # noqa automaticamente em todas as linhas com erro. Isso permite limpar o backlog gradualmente sem bloquear o CI imediatamente.

🚀
Pro tip

O Ruff suporta a configuração per-file-ignores no pyproject.toml, que permite desativar regras específicas apenas em certos arquivos. Útil para arquivos de migração de banco, testes com padrões diferentes ou código gerado automaticamente.

Vale a pena?

Sim, sem ressalvas para a maioria dos projetos Python. O Ruff elimina a necessidade de manter configurações separadas de Flake8, Black e isort, e e drasticamente mais rápido. A expansão para 413 regras no 0.16.0 só aumenta o valor da ferramenta.

O único cenário onde você pode hesitar e se o projeto tem dependências muito específicas de plugins do Flake8 que ainda não tem equivalente no Ruff. Consulte a página de compatibilidade do Ruff para verificar antes de migrar.

Para começar, instale o Ruff, rode ruff check . no seu projeto e veja o que aparece. A lista de erros pode surpreender, mas cada um deles e um problema real que vale corrigir.