Ruff no Python: lint e formatação de código passo a passo

Manter um projeto Python organizado vai muito além de escolher bons nomes para variáveis. À medida que o código cresce, pequenos problemas de estilo, imports desordenados, trechos não utilizados e erros simples começam a consumir tempo nas revisões. O Ruff no Python ajuda a automatizar essa verificação ao reunir lint, organização de imports e formatação em uma ferramenta rápida e fácil de configurar.

Neste guia, você vai instalar o Ruff, executar as primeiras verificações, aplicar correções automáticas com segurança, configurar o pyproject.toml, integrar a ferramenta ao VS Code e preparar o projeto para uma rotina de integração contínua. Antes de avançar, vale revisar o nosso conteúdo sobre PEP 8 no Python, porque o Ruff transforma várias dessas recomendações em verificações automáticas.

O que é Ruff no Python?

Ruff é uma ferramenta de análise estática criada para encontrar problemas em arquivos Python sem precisar executar o programa. A documentação oficial apresenta o linter como uma alternativa rápida a combinações de ferramentas como Flake8, isort, pydocstyle, pyupgrade e autoflake. O projeto também inclui um formatador acessado pelo comando ruff format. Consulte a documentação oficial do Ruff para conhecer todas as regras e opções disponíveis.

Na prática, isso permite usar uma única configuração para detectar imports não utilizados, organizar imports, apontar variáveis esquecidas, identificar erros de sintaxe, aplicar regras de modernização e padronizar a apresentação do código. O Ruff não substitui testes automatizados nem análise de tipos, mas reduz uma grande quantidade de problemas repetitivos antes que eles cheguem à revisão humana.

Por que usar Ruff em projetos Python?

• Feedback rápido: a verificação pode ser executada a cada salvamento, antes de um commit ou dentro do pipeline.
• Configuração centralizada: regras, exclusões e formato ficam no pyproject.toml.
• Menos ferramentas separadas: lint, imports e formatação podem fazer parte do mesmo fluxo.
• Correções automáticas: vários avisos podem ser resolvidos com ruff check --fix.
• Consistência: todos os participantes do projeto aplicam o mesmo padrão.

Essa consistência é especialmente útil em equipes, cursos e projetos públicos. Em vez de discutir manualmente cada espaço ou import, a equipe define as regras uma vez e deixa a ferramenta cuidar do trabalho mecânico. Para projetos maiores, combine o Ruff com Pytest no Python para verificar comportamento, e com type hints para melhorar a clareza das interfaces.

Como instalar Ruff no Python

Crie ou ative um ambiente isolado antes de instalar ferramentas do projeto. Nosso tutorial sobre ambiente virtual com venv mostra o processo completo no Windows, macOS e Linux. Depois de ativar o ambiente, execute:

python -m pip install ruff

Confirme a instalação exibindo a versão:

ruff --version

Também é possível adicionar Ruff ao grupo de dependências de desenvolvimento do Poetry, uv ou outro gerenciador. O ponto importante é registrar a ferramenta no projeto, para que outra pessoa consiga reproduzir o mesmo ambiente. Caso ainda tenha dúvidas sobre pacotes, veja como instalar bibliotecas no Python com pip.

Primeira verificação com ruff check

Abra o terminal na raiz do projeto e execute o comando abaixo. O ponto representa o diretório atual, então o Ruff procura arquivos Python dentro dele e de suas subpastas.

ruff check .

Imagine um arquivo chamado app.py com um import não utilizado e imports fora de ordem:

import sys
import os


def saudacao(nome):
    mensagem = "Olá"
    return f"Olá, {nome}!"


print(saudacao("Ana"))

Ao executar a verificação, o Ruff pode apontar o import não utilizado e regras relacionadas à organização. O resultado mostra o arquivo, a linha, a coluna, o código da regra e uma descrição. Esse código é importante porque permite consultar a regra na documentação ou ignorá-la de maneira específica quando existe uma justificativa real.

Aplicando correções automáticas

Para corrigir automaticamente problemas considerados seguros e compatíveis com as regras selecionadas, use:

ruff check . --fix

Mesmo com automação, revise as alterações no Git antes de confirmá-las. A opção --fix economiza tempo, mas não elimina a responsabilidade de entender o que mudou. Uma rotina segura é executar o comando, analisar o diff, rodar os testes e somente depois criar o commit.

Como formatar código com Ruff

O linter procura problemas; o formatador reorganiza a aparência do código. Para formatar todos os arquivos Python do projeto, execute:

ruff format .

Durante uma verificação no pipeline, normalmente você não quer modificar arquivos. Nesse caso, use o modo de checagem:

ruff format --check .

A documentação do formatador Ruff descreve o comando como uma opção compatível com o estilo adotado pelo Black. Em um projeto novo, o mais simples é escolher um único formatador principal. Manter dois formatadores atuando sobre os mesmos arquivos pode gerar alterações alternadas e ruído desnecessário nos commits.

Configurando Ruff no pyproject.toml

O arquivo pyproject.toml é um lugar central para configurações de ferramentas Python. O Guia de Empacotamento da Python Packaging Authority explica que ferramentas como linters podem usar subtabelas dentro de [tool]. Na raiz do projeto, crie ou edite o arquivo com uma configuração inicial:

[tool.ruff]
line-length = 88
target-version = "py311"
exclude = [".venv", "build", "dist"]

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

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
line-ending = "auto"

A opção line-length define o comprimento preferido das linhas. target-version informa a versão mínima de Python que o projeto pretende suportar. A lista exclude evita analisar ambientes virtuais e diretórios gerados. Em select, os prefixos ativam famílias de regras: erros básicos de estilo, erros de sintaxe e lógica do Pyflakes, além da organização de imports.

Comece com poucas famílias de regras e aumente gradualmente. Ativar centenas de verificações em um projeto antigo pode produzir uma lista enorme de alertas e desmotivar a equipe. Uma migração eficiente corrige primeiro os problemas críticos, registra a configuração e amplia o conjunto em etapas pequenas.

Ignorando uma regra com critério

Quando uma regra não faz sentido para o projeto inteiro, ela pode ser adicionada a ignore. Para uma exceção localizada, use um comentário # noqa: CÓDIGO na linha correspondente. Prefira sempre informar o código exato em vez de usar um # noqa genérico, porque isso preserva outras verificações úteis.

resultado = chamada_legada()  # noqa: F841

Uma exceção deve ter motivo claro. Se muitas linhas precisam ignorar a mesma regra, talvez seja melhor revisar a configuração, refatorar o código ou usar uma exclusão por arquivo. O objetivo do lint não é obter uma tela verde a qualquer custo, e sim tornar problemas reais mais fáceis de encontrar.

Integração com VS Code

Instale a extensão oficial Ruff no VS Code e abra a pasta raiz do projeto. A extensão pode mostrar diagnósticos no editor, organizar imports e formatar arquivos. Se você já utiliza outras extensões de lint ou formatação, desative funções duplicadas para evitar mensagens repetidas e conflitos. Nosso guia de extensões do VS Code para Python ajuda a montar um ambiente mais enxuto.

Uma configuração comum é habilitar a formatação ao salvar e definir Ruff como formatador padrão para arquivos Python. Ainda assim, o pyproject.toml deve continuar sendo a fonte principal das regras. Configurações exclusivas do editor dificultam a reprodução no terminal e no pipeline.

Executando Ruff antes de cada commit

A verificação manual funciona no início, mas é fácil esquecê-la. Você pode criar um script simples, um hook com pre-commit ou um comando do gerenciador de tarefas do projeto. Uma sequência mínima é:

ruff check .
ruff format --check .
pytest

Essa ordem verifica problemas de código, confirma a formatação e executa testes. Se qualquer etapa falhar, o commit ou pipeline deve ser interrompido. Em projetos existentes, comece aplicando o fluxo apenas aos arquivos alterados e amplie a cobertura à medida que o código antigo for corrigido.

Ruff em integração contínua

No GitHub Actions, GitLab CI ou outro serviço, instale as dependências e execute os mesmos comandos usados localmente. Evite criar uma configuração especial para o servidor. O valor da integração contínua está em reproduzir o fluxo do desenvolvedor em um ambiente limpo.

python -m pip install ruff pytest
ruff check .
ruff format --check .
pytest

Fixe versões conforme a política do projeto e atualize de forma consciente. Uma nova versão pode adicionar regras, modificar comportamento de formatação ou tornar correções disponíveis. Teste a atualização em uma branch e leia as notas de versão antes de aplicá-la a todos os repositórios.

Ruff, Black, Flake8 e isort: qual escolher?

Não existe obrigação de migrar um projeto estável. Avalie o custo de troca, plugins utilizados e compatibilidade com o padrão atual. Em projetos novos, Ruff reduz a quantidade de dependências e configurações. Em projetos legados, uma migração gradual costuma ser mais segura do que substituir todas as ferramentas de uma vez.

Erros comuns ao começar

• Executar --fix sem revisar: sempre confira o diff e rode os testes.
• Ativar regras demais: comece com um conjunto pequeno e útil.
• Manter dois formatadores: escolha um responsável pela formatação dos mesmos arquivos.
• Configurar apenas o editor: registre as regras no repositório.
• Analisar a pasta do ambiente virtual: exclua .venv e diretórios gerados.
• Ignorar alertas genericamente: use códigos específicos e documente exceções.

Fluxo recomendado para um projeto novo

Crie o ambiente virtual, instale Ruff e Pytest, adicione a configuração ao pyproject.toml e faça uma primeira execução. Em seguida, formate o código, corrija os alertas, registre tudo no Git e configure o editor. Por fim, replique os mesmos comandos na integração contínua.

Esse processo cria uma base previsível: o editor oferece retorno imediato, o terminal permite validação manual e o pipeline impede que problemas conhecidos cheguem à branch principal. O Ruff cuida do trabalho repetitivo, enquanto revisores podem concentrar atenção em arquitetura, segurança, regras de negócio e legibilidade.

Perguntas frequentes

Ruff substitui testes automatizados?

Não. Ruff analisa padrões e problemas estáticos, mas não confirma se o programa entrega o resultado correto. Use testes unitários e de integração para validar comportamento.

Posso usar Ruff apenas como linter?

Sim. Você pode executar somente ruff check e manter outro formatador. Nesse caso, configure as ferramentas para que não disputem as mesmas responsabilidades.

Ruff funciona em projetos antigos?

Funciona, mas a adoção deve ser gradual. Selecione poucas regras, corrija os alertas mais importantes e aumente o rigor com o tempo.

Devo usar ruff check –fix no pipeline?

Normalmente o pipeline deve apenas verificar e falhar, sem modificar arquivos. As correções automáticas são mais adequadas ao ambiente local ou a um bot criado especificamente para propor alterações.

Onde devo guardar a configuração?

O pyproject.toml na raiz do repositório é uma escolha prática, pois pode centralizar Ruff e outras ferramentas do ecossistema Python.

Conclusão

Usar Ruff no Python é uma forma eficiente de tornar lint, organização de imports e formatação parte natural do desenvolvimento. Comece com uma configuração simples, revise as correções automáticas, mantenha as regras no repositório e execute os mesmos comandos no editor, terminal e pipeline.

A ferramenta entrega mais valor quando faz parte de um conjunto de boas práticas. Ambientes virtuais garantem isolamento, testes protegem o comportamento e revisões humanas analisam decisões que nenhuma ferramenta automática entende completamente. Com essa combinação, o projeto fica mais consistente, fácil de manter e preparado para crescer.