unref encontra código morto em Python (funções, classes, métodos, variáveis e atributos que nada no projeto usa) com um único comando, e em nosso teste foi cerca de oito vezes mais rápido que vulture. Está escrito em Rust sobre o parser do Ruff, segue suas convenções e seu formato de saída, e é executado com uvx unref.
yoDEV Tested · 17 de novembro de 2026
Executamos unref 0.2.1 e vulture 2.16 em um container Linux com 2 vCPU sobre o repositório de rich (212 arquivos.py). Os resultados que apresentamos como nossos vêm desse teste.
Testamos lado a lado com vulture em um repositório real para ver em que coincidem, em que não e que falsos positivos você vai ter que silenciar.
O que é código morto e o que detecta unref?
Código morto é uma definição que continua no repositório mas que nada chama, lê nem importa. Custa tempo de revisão, tempo de testes e confusão, e a natureza dinâmica de Python torna difícil encontrá-lo à mão.
unref reporta cinco tipos de definição sem uso:
| Código da regra | O que reporta |
|---|---|
unused-function |
Uma função, incluindo as aninhadas |
unused-class |
Uma classe |
unused-method |
Uma função definida diretamente dentro de uma classe |
unused-variable |
Uma variável a nível de módulo |
unused-attribute |
Um atributo de classe ou de instância (self.value = ...) |
Também revisa seus próprios comentários de supressão (unused-ignore-comment, invalid-ignore-comment, ignore-comment-unknown-rule) e reporta os arquivos que não consegue analisar ou ler (invalid-syntax, io-error): os ignora sem parar a execução.
Ruff detecta código morto?
Não: Ruff ainda não detecta funções nem classes sem uso (o pedido continua aberto como astral-sh/ruff#872), e esse é o vazio que unref preenche. De forma inversa, unref deixa de propósito os imports e as variáveis locais sem uso: sua documentação os deixa nas mãos de Ruff e esclarece que as duas ferramentas estão pensadas para serem usadas juntas.
Na prática, se já usas Ruff, unref não te pede aprender nada novo: lê a configuração de pyproject.toml, imprime os achados com o mesmo estilo de Ruff e se instala como um hook a mais junto aos de Ruff.
Como encontrar código morto em Python com unref?
Não precisa instalá-lo. Com uv disponível, basta com:
uvx unref
Sem argumentos, revisa o projeto que contém o diretório atual. Para revisar caminhos específicos:
uvx unref src scripts
Cada achado se imprime ao estilo de Ruff, caminho:linha:coluna: código-da-regra 'nome':
rich/_export_format.py:75:1: unused-variable '_SVG_FONT_FAMILY'
O comando termina com um código de saída diferente de zero quando encontra algo, assim pode fazer falhar um job de CI ou um hook de commit sem configuração extra. O pacote no PyPI requer Python 3.11 ou superior.
Unref vs vulture: qual encontra melhor o código morto em Python?
vulture é o buscador de código morto em Python com mais trajetória, e a ferramenta que a maioria de quem busca esse tema já conhece. Executamos ambos sobre o mesmo código:
- Repositório: Textualize/rich, commit
3a109cc(2026-11-07), 212 arquivos.py - Versões: unref 0.2.1 e vulture 2.16, ambos com a configuração padrão
- Máquina: um container Linux com 2 vCPU
- Escopo: unref sobre o projeto completo; vulture sobre todos os diretórios com código (
rich tests examples docs tools benchmarks)
| unref 0.2.1 | vulture 2.16 | |
|---|---|---|
| Tempo por execução | 0,08–0,10 s (5 execuções) | 0,65–0,87 s (3 execuções) |
| Achados | 105 | 138 (confiança mínima padrão: 60%) |
Achados com --min-confidence 100 |
— | 13 |
| Código de saída quando encontra algo | 1 | 3 |
Velocidade. unref foi cerca de oito vezes mais rápido em nossa máquina. O README afirma que é “20x faster than vulture” e que revisa todo CPython em menos de um segundo; esse é o benchmark do próprio autor, executado com scripts/benchmark.py do repositório sobre uns 2.300 arquivos. Em um repositório desse tamanho, o arranque do processo pesa muito no total, assim nossa cifra é um piso, não uma contradição. De qualquer forma, ambas as ferramentas são rápidas o bastante para um hook de pre-commit; unref é a que nem você vai notar.
Coincidências. Comparando os achados por arquivo e nome, as duas ferramentas coincidiram em 31 definições. O interessante está nas diferenças:
- unref reporta o início de cada cadeia, não cada elo. 31 dos achados extra de vulture são métodos de classes de benchmark que, por sua vez, não se usam. unref reporta a classe e para aí: se uma classe está morta, você vê a classe, não cada um de seus métodos. Com
show-transitive = truese imprime a cadeia completa, e o código de saída é o mesmo em ambos os casos. - unref conhece vários frameworks de série. vulture marcou os 13 ajustes do
docs/source/conf.pyde Sphinx (project,extensions,html_theme…), os campos de classes attrs e dataclass, um fixture de pytest e dois marcadorespytestmark. unref 0.2.1 não marcou nenhum, porque suas regras integradas sabem que esses nomes são lidos pelo framework. As regras integradas cobrem pytest, unittest, Pydantic, dataclasses (incluindo attrs eNamedTuple), SQLAlchemy, FastAPI, Flask e Sphinx, e vêm todas ativadas. - Parte do que reporta vulture fica fora do alcance de unref. vulture também reporta argumentos de função sem uso (
__n,__limit,objtype…) e variáveis locais. unref não cobre nenhum dos dois: sua documentação deixa as variáveis locais a Ruff e não tem regra para argumentos. - unref encontrou código morto real que vulture passou batido.
_SVG_FONT_FAMILYe_SVG_CLASSES_PREFIX, emrich/_export_format.py, estão definidas e não se referenciam em nenhuma outra parte do repositório. vulture não as reportou.
Que falsos positivos dá unref?
As duas ferramentas analisam o código sem executá-lo, assim nenhuma vê os nomes a que só se chega de forma dinâmica. Em nosso teste, unref marcou:
cell_tableem cada um dos 21 arquivosrich/_unicode_data/unicode*.py. Se carregam comimportlib.import_modulee se leem comomodule.cell_table, algo que nenhuma ferramenta estática consegue seguir.rich_proxied_file, que se busca comgetattr(file, "rich_proxied_file", file).readinto, um método do protocolo de I/O a que chama a maquinaria de I/O de Python, não o projeto.
Há uma categoria a mais que convém pensar antes de apagar nada: a API pública. Em uma biblioteca como rich, nomes como box.MARKDOWN não se usam dentro do repositório porque existem para quem usa a biblioteca. Os buscadores de código morto são mais confiáveis em aplicações; em uma biblioteca, leia cada nome público como “sem uso interno”, não como “seguro de apagar”.
Como silenciar um falso positivo em unref?
Para uma única linha, adicione um comentário de supressão com o código da regra:
self.name = name # unref: ignore[unused-attribute]
Vários códigos vão separados por vírgula, como em # unref: ignore[unused-function, unused-class]. Um # unref: ignore sem código se reporta por sua vez como invalid-ignore-comment, e um comentário que já não suprime nada se reporta como unused-ignore-comment, assim as supressões obsoletas não se acumulam.
Para os nomes que usa um framework ou uma busca dinâmica, a documentação recomenda usar a configuração. Os ajustes vão na tabela [tool.unref] de pyproject.toml. Este override eliminaria os 21 achados de cell_table de nosso teste:
[[tool.unref.overrides]]
paths = ["rich/_unicode_data"]
used-names = ["cell_table"]
Outras chaves documentadas:
used-names: nomes que sempre contam como usados, com padrões*,?e[abc](used-names = ["handle_*", "visit_*"]).used-decorators: decoradores, pelo seu nome completo com pontos e sem@, que marcam como usado o que decoram (used-decorators = ["app.command"]).exclude: caminhos que não se revisa, com sintaxe de.gitignore.python: o ambiente do qual se leem as classes base instaladas. Por padrão usa o ambiente virtual ativo ou o.venvdo projeto, e não importa nem executa nada.- Os overrides também podem selecionar por
base-classesouclass-decorators; por exemplo,base-classes = ["ast.NodeVisitor"]comused-names = ["visit_*"].
Como usar unref com pre-commit e GitHub Actions?
O hook de pre-commit vai em .pre-commit-config.yaml, junto aos hooks de Ruff:
- repo: https://github.com/Apakottur/unref
rev: v0.2.1
hooks:
- id: unref
v0.2.1 era a tag mais recente ao momento de publicar esta nota. O projeto está publicando várias versões por semana, assim execute pre-commit autoupdate para passar à atual. O hook sempre revisa o projeto completo, porque uma definição só conta como sem uso se nenhum arquivo a referencia.
No GitHub Actions, a documentação mostra dois passos: uv sync (opcional, para que unref possa seguir as classes base de suas dependências instaladas) e depois:
uvx unref --output-format github
Esse formato converte cada achado em uma anotação sobre os arquivos modificados do pull request.
Unref é grátis e está pronto para usar?
Sim, é grátis: unref tem licença MIT. O que convém saber é que é um projeto em fase temprana, e isso se nota em um detalhe concreto. Passou de 0.0.1 a 0.2.1 entre 11 e 17 de novembro de 2026, com doze versões em seus primeiros seis dias.
O site de documentação segue o ramo de desenvolvimento, não a última versão publicada. Quando começamos este teste com a 0.2.0, as regras de dataclasses e Sphinx que a documentação descreve ainda não estavam incluídas. Chegaram na 0.2.1, publicada em 17 de novembro de 2026. Se uma regra documentada não se comporta como diz a documentação, revise primeiro uvx unref --version.
Ao momento de publicar esta nota não há ainda um histórico de adoção, e o autor pede que os falsos positivos se reportem como issues no GitHub. Como unref termina com erro quando encontra algo e lê seus ajustes de pyproject.toml, adicioná-lo a um projeto e removê-lo são mudanças de uma linha. Executá-lo uma vez sobre seu código é a forma mais barata de saber se merece um lugar em seus hooks.
E você? Que ferramenta usa hoje para encontrar código morto em seus projetos de Python?
- Em cada commit (pre-commit ou CI)
- Quando faço uma refatoração grande
- Quase nunca
- Prefiro outra opção (nos conte qual)
Comente abaixo ou, se este artigo chegou para você por email, responda diretamente ao email: sua resposta se publica aqui.
Relacionado: Python 3.15 já está disponível: o que se quebra ao atualizar e as duas mudanças que você deve testar primeiro
