unref encuentra código muerto en Python (funciones, clases, métodos, variables y atributos que nada en el proyecto usa) con un solo comando, y en nuestra prueba fue unas ocho veces más rápido que vulture. Está escrito en Rust sobre el parser de Ruff, sigue sus convenciones y su formato de salida, y se ejecuta con uvx unref.
yoDEV Tested · 17 de noviembre de 2026
Ejecutamos unref 0.2.1 y vulture 2.16 en un contenedor Linux con 2 vCPU sobre el repositorio de rich (212 archivos.py). Los resultados que reportamos como nuestros salen de esa prueba.
Lo probamos lado a lado con vulture en un repositorio real para ver en qué coinciden, en qué no y qué falsos positivos vas a tener que silenciar.
¿Qué es el código muerto y qué detecta unref?
El código muerto (en inglés, dead code o unreferenced code) es una definición que sigue en el repositorio pero que nada llama, lee ni importa. Cuesta tiempo de revisión, tiempo de tests y confusión, y la naturaleza dinámica de Python hace que sea difícil encontrarlo a mano.
unref reporta cinco tipos de definición sin usar:
| Código de regla | Qué reporta |
|---|---|
unused-function |
Una función, incluidas las anidadas |
unused-class |
Una clase |
unused-method |
Una función definida directamente dentro de una clase |
unused-variable |
Una variable a nivel de módulo |
unused-attribute |
Un atributo de clase o de instancia (self.value = ...) |
También revisa sus propios comentarios de supresión (unused-ignore-comment, invalid-ignore-comment, ignore-comment-unknown-rule) y reporta los archivos que no puede analizar o leer (invalid-syntax, io-error): los salta sin detener la ejecución.
¿Ruff detecta código muerto?
No: Ruff todavía no detecta funciones ni clases sin usar (la petición sigue abierta como astral-sh/ruff#872), y ese es el hueco que cubre unref. A la inversa, unref deja fuera a propósito los imports y las variables locales sin usar: su documentación los deja en manos de Ruff y aclara que las dos herramientas están pensadas para usarse juntas.
En la práctica, si ya usas Ruff, unref no te pide aprender nada nuevo: lee la configuración desde pyproject.toml, imprime los hallazgos con el mismo estilo de Ruff y se instala como un hook más junto a los de Ruff.
¿Cómo encontrar código muerto en Python con unref?
No necesitas instalarlo. Con uv disponible, basta con:
uvx unref
Sin argumentos, revisa el proyecto que contiene el directorio actual. Para revisar rutas concretas:
uvx unref src scripts
Cada hallazgo se imprime al estilo de Ruff, ruta:línea:columna: código-de-regla 'nombre':
rich/_export_format.py:75:1: unused-variable '_SVG_FONT_FAMILY'
El comando termina con un código de salida distinto de cero cuando encuentra algo, así que puede hacer fallar un job de CI o un hook de commit sin configuración extra. El paquete en PyPI requiere Python 3.11 o superior.
Unref vs vulture: ¿cuál encuentra mejor el código muerto en Python?
vulture es el buscador de código muerto de Python con más trayectoria, y la herramienta que la mayoría de quienes buscan este tema ya conoce. Ejecutamos ambos sobre el mismo código:
- Repositorio: Textualize/rich, commit
3a109cc(2026-11-07), 212 archivos.py - Versiones: unref 0.2.1 y vulture 2.16, ambos con la configuración por defecto
- Máquina: un contenedor Linux con 2 vCPU
- Alcance: unref sobre el proyecto completo; vulture sobre todos los directorios con código (
rich tests examples docs tools benchmarks)
| unref 0.2.1 | vulture 2.16 | |
|---|---|---|
| Tiempo por ejecución | 0,08–0,10 s (5 ejecuciones) | 0,65–0,87 s (3 ejecuciones) |
| Hallazgos | 105 | 138 (confianza mínima por defecto: 60%) |
Hallazgos con --min-confidence 100 |
— | 13 |
| Código de salida cuando encuentra algo | 1 | 3 |
Velocidad. unref fue unas ocho veces más rápido en nuestra máquina. El README afirma que es “20x faster than vulture” y que revisa todo CPython en menos de un segundo; ese es el benchmark del propio autor, ejecutado con el scripts/benchmark.py del repositorio sobre unos 2.300 archivos. En un repositorio de este tamaño, el arranque del proceso pesa mucho en el total, así que nuestra cifra es un piso, no una contradicción. En cualquier caso, ambas herramientas son lo bastante rápidas para un hook de pre-commit; unref es la que ni vas a notar.
Coincidencias. Comparando los hallazgos por archivo y nombre, las dos herramientas coincidieron en 31 definiciones. Lo interesante está en las diferencias:
- unref reporta el inicio de cada cadena, no cada eslabón. 31 de los hallazgos extra de vulture son métodos de clases de benchmark que, a su vez, no se usan. unref reporta la clase y se detiene ahí: si una clase está muerta, ves la clase, no cada uno de sus métodos. Con
show-transitive = truese imprime la cadena completa, y el código de salida es el mismo en ambos casos. - unref conoce varios frameworks de serie. vulture marcó los 13 ajustes del
docs/source/conf.pyde Sphinx (project,extensions,html_theme…), los campos de clases attrs y dataclass, un fixture de pytest y dos marcadorespytestmark. unref 0.2.1 no marcó ninguno, porque sus reglas integradas saben que esos nombres los lee el framework. Las reglas integradas cubren pytest, unittest, Pydantic, dataclasses (incluidos attrs yNamedTuple), SQLAlchemy, FastAPI, Flask y Sphinx, y vienen todas activadas. - Parte de lo que reporta vulture queda fuera del alcance de unref. vulture también reporta argumentos de función sin usar (
__n,__limit,objtype…) y variables locales. unref no cubre ninguno de los dos: su documentación deja las variables locales a Ruff y no tiene regla para argumentos. - unref encontró código muerto real que vulture pasó por alto.
_SVG_FONT_FAMILYy_SVG_CLASSES_PREFIX, enrich/_export_format.py, están definidas y no se referencian en ninguna otra parte del repositorio. vulture no las reportó.
¿Qué falsos positivos da unref?
Las dos herramientas analizan el código sin ejecutarlo, así que ninguna ve los nombres a los que solo se llega de forma dinámica. En nuestra prueba, unref marcó:
cell_tableen cada uno de los 21 archivosrich/_unicode_data/unicode*.py. Se cargan conimportlib.import_moduley se leen comomodule.cell_table, algo que ninguna herramienta estática puede seguir.rich_proxied_file, que se busca congetattr(file, "rich_proxied_file", file).readinto, un método del protocolo de I/O al que llama la maquinaria de I/O de Python, no el proyecto.
Hay una categoría más que conviene pensar antes de borrar nada: la API pública. En una biblioteca como rich, nombres como box.MARKDOWN no se usan dentro del repositorio porque existen para quienes usan la biblioteca. Los buscadores de código muerto son más fiables en aplicaciones; en una biblioteca, lee cada nombre público como “sin uso interno”, no como “seguro de borrar”.
¿Cómo silenciar un falso positivo en unref?
Para una sola línea, añade un comentario de supresión con el código de la regla:
self.name = name # unref: ignore[unused-attribute]
Varios códigos van separados por comas, como en # unref: ignore[unused-function, unused-class]. Un # unref: ignore sin código se reporta a su vez como invalid-ignore-comment, y un comentario que ya no suprime nada se reporta como unused-ignore-comment, así que las supresiones obsoletas no se acumulan.
Para los nombres que usa un framework o una búsqueda dinámica, la documentación recomienda usar la configuración. Los ajustes van en la tabla [tool.unref] de pyproject.toml. Este override eliminaría los 21 hallazgos de cell_table de nuestra prueba:
[[tool.unref.overrides]]
paths = ["rich/_unicode_data"]
used-names = ["cell_table"]
Otras claves documentadas:
used-names: nombres que siempre cuentan como usados, con patrones*,?y[abc](used-names = ["handle_*", "visit_*"]).used-decorators: decoradores, por su nombre completo con puntos y sin@, que marcan como usado lo que decoran (used-decorators = ["app.command"]).exclude: rutas que no se revisan, con sintaxis de.gitignore.python: el entorno del que se leen las clases base instaladas. Por defecto usa el entorno virtual activo o el.venvdel proyecto, y no importa ni ejecuta nada.- Los overrides también pueden seleccionar por
base-classesoclass-decorators; por ejemplo,base-classes = ["ast.NodeVisitor"]conused-names = ["visit_*"].
¿Cómo usar unref con pre-commit y GitHub Actions?
El hook de pre-commit (o prek) va en .pre-commit-config.yaml, junto a los hooks de Ruff:
- repo: https://github.com/Apakottur/unref
rev: v0.2.1
hooks:
- id: unref
v0.2.1 era el tag más reciente al momento de publicar esta nota. El proyecto está publicando varias versiones por semana, así que ejecuta pre-commit autoupdate (o prek autoupdate) para pasar a la actual. El hook siempre revisa el proyecto completo, porque una definición solo cuenta como sin usar si ningún archivo la referencia.
En GitHub Actions, la documentación muestra dos pasos: uv sync (opcional, para que unref pueda seguir las clases base de tus dependencias instaladas) y luego:
uvx unref --output-format github
Ese formato convierte cada hallazgo en una anotación sobre los archivos modificados del pull request.
¿Unref es gratis y está listo para usar?
Sí, es gratis: unref tiene licencia MIT. Lo que conviene saber es que es un proyecto en fase temprana, y eso se nota en un detalle concreto. Pasó de la 0.0.1 a la 0.2.1 entre el 11 y el 17 de noviembre de 2026, con doce versiones en sus primeros seis días.
El sitio de documentación sigue la rama de desarrollo, no la última versión publicada. Cuando empezamos esta prueba con la 0.2.0, las reglas de dataclasses y Sphinx que describe la documentación todavía no estaban incluidas. Llegaron en la 0.2.1, publicada el 17 de noviembre de 2026. Si una regla documentada no se comporta como dice la documentación, revisa primero uvx unref --version.
Al momento de publicar esta nota no hay todavía un historial de adopción, y el autor pide que los falsos positivos se reporten como issues en GitHub. Como unref termina con error cuando encuentra algo y lee sus ajustes desde pyproject.toml, añadirlo a un proyecto y quitarlo son cambios de una línea. Ejecutarlo una vez sobre tu código es la forma más barata de saber si merece un lugar en tus hooks.
¿Y tú? ¿Qué herramienta usas hoy para encontrar código muerto en tus proyectos de Python?
- En cada commit (pre-commit o CI)
- Cuando hago una refactorización grande
- Casi nunca
- Prefiero otra opción (cuéntanos cuál)
Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.
Relacionado: Python 3.15 ya está disponible: qué se rompe al actualizar y los dos cambios que debes probar primero
