Ruff en Python: lint y formato de código paso a paso

Mantener un proyecto Python organizado implica mucho más que elegir buenos nombres para las variables. Cuando el código crece, los pequeños problemas de estilo, los imports desordenados, el código sin usar y los errores simples empiezan a consumir tiempo durante las revisiones. Ruff en Python automatiza gran parte de ese trabajo al reunir lint, organización de imports y formato en una herramienta rápida y sencilla de configurar.

En esta guía aprenderás a instalar Ruff, ejecutar las primeras comprobaciones, aplicar correcciones automáticas con seguridad, configurar pyproject.toml, integrar la herramienta con VS Code y prepararla para integración continua. También conviene revisar nuestra guía de PEP 8 en Python, porque Ruff convierte muchas recomendaciones de estilo en comprobaciones automáticas y repetibles.

¿Qué es Ruff en Python?

Ruff es una herramienta de análisis estático que encuentra problemas en archivos Python sin ejecutar la aplicación. Su documentación oficial describe el linter como una alternativa rápida a combinaciones basadas en Flake8 y muchos de sus plugins, isort, pydocstyle, pyupgrade y autoflake. El proyecto también incluye un formateador disponible mediante ruff format. Consulta la documentación oficial de Ruff para conocer todas las reglas y opciones.

En la práctica, una sola configuración puede detectar imports sin usar, ordenar imports, señalar variables olvidadas, encontrar problemas de sintaxis, aplicar reglas de modernización y mantener una presentación consistente. Ruff no sustituye las pruebas automatizadas ni la comprobación de tipos, pero elimina una gran cantidad de observaciones repetitivas antes de que el código llegue a una revisión humana.

¿Por qué usar Ruff en un proyecto Python?

• Respuesta rápida: las comprobaciones pueden ejecutarse al guardar, antes de un commit o dentro del pipeline.
• Configuración centralizada: reglas, exclusiones y formato pueden vivir en pyproject.toml.
• Menos herramientas separadas: lint, imports y formato comparten el mismo flujo.
• Correcciones automáticas: muchos avisos se resuelven con ruff check --fix.
• Consistencia: todos los colaboradores aplican las mismas reglas.

Esta consistencia resulta útil en equipos, cursos y repositorios públicos. En lugar de discutir cada espacio o import durante la revisión, el equipo define las reglas mecánicas una sola vez. Combina Ruff con pruebas y una estructura clara. Nuestra guía de tests unitarios en Python ayuda a completar ese flujo de calidad.

Cómo instalar Ruff

Crea o activa un entorno aislado antes de instalar herramientas del proyecto. El tutorial sobre entornos virtuales con venv explica el proceso en Windows, macOS y Linux. Después de activar el entorno, ejecuta:

python -m pip install ruff

Comprueba que el comando está disponible:

ruff --version

También puedes añadir Ruff a un grupo de dependencias de desarrollo administrado con Poetry, uv u otra herramienta. Lo importante es registrar la dependencia para que otra persona pueda reproducir el mismo entorno. Para revisar el flujo completo con pip, consulta cómo instalar bibliotecas de Python con pip.

Primera comprobación con ruff check

Abre una terminal en la raíz del proyecto y ejecuta el siguiente comando. El punto representa el directorio actual, de modo que Ruff busca archivos Python dentro de esa carpeta y sus subcarpetas.

ruff check .

Imagina un archivo app.py con un import sin usar y varios imports fuera de orden:

import sys
import os


def saludar(nombre):
    mensaje = "Hola"
    return f"Hola, {nombre}!"


print(saludar("Ana"))

El resultado muestra el archivo, la línea, la columna, el código de la regla y una explicación breve. Ese código permite consultar la documentación exacta o crear una excepción limitada cuando existe una razón legítima. No conviene tratar todos los avisos como simples detalles visuales, porque algunas familias de reglas revelan errores reales.

Aplicar correcciones automáticas

Para aplicar las correcciones disponibles para las reglas seleccionadas, utiliza:

ruff check . --fix

Revisa siempre el diff de Git antes de confirmar los cambios. Las correcciones automáticas ahorran tiempo, pero no eliminan la necesidad de entender lo que cambió. Una rutina segura consiste en ejecutar el comando, inspeccionar el diff, correr las pruebas y crear el commit solamente después.

Cómo dar formato al código con Ruff

El linter busca problemas; el formateador reescribe la presentación del código de forma consistente. Para formatear todos los archivos Python encontrados, ejecuta:

ruff format .

Un trabajo de CI normalmente debe verificar el formato sin modificar los archivos. Para eso, utiliza el modo de comprobación:

ruff format --check .

La documentación del formateador Ruff lo presenta como una herramienta diseñada para ser compatible con el estilo de Black. En un repositorio nuevo, elige un único formateador principal. Ejecutar dos formateadores sobre los mismos archivos puede provocar cambios alternados y commits con ruido.

Configurar Ruff en pyproject.toml

El archivo pyproject.toml es un lugar central para las herramientas de un proyecto Python. La Guía de Usuario de Python Packaging explica que las configuraciones específicas de herramientas se guardan en subtables de [tool]. Crea o actualiza el archivo en la raíz del repositorio con una configuración 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"

line-length define el ancho preferido de las líneas. target-version indica la versión mínima de Python que admite el proyecto. exclude evita analizar entornos virtuales y carpetas generadas. Los prefijos de select activan comprobaciones básicas de estilo, errores importantes de sintaxis y lógica, y organización de imports.

Empieza con un conjunto reducido y amplíalo gradualmente. Activar cientos de reglas en un proyecto antiguo puede generar miles de avisos sin un plan realista para corregirlos. Una migración eficaz resuelve primero los problemas críticos, registra la configuración base y añade nuevas familias en pasos pequeños.

Ignorar una regla con criterio

Cuando una regla no encaja en todo el repositorio, puede añadirse a la lista de ignoradas. Para una excepción local y justificada, usa # noqa: CÓDIGO en la línea correspondiente. Es mejor indicar el código exacto que emplear un # noqa genérico, porque así se conservan otras comprobaciones útiles.

resultado = llamada_legada()  # noqa: F841

Toda excepción necesita una razón. Si muchas líneas requieren la misma supresión, revisa la selección de reglas, refactoriza el código o crea una configuración por archivo. El objetivo no es conseguir un comando verde a cualquier precio, sino facilitar la detección de problemas significativos.

Integración de Ruff con VS Code

Instala la extensión oficial Ruff, abre la raíz del proyecto y permite que el editor lea la configuración del repositorio. La extensión puede mostrar diagnósticos, ordenar imports y formatear archivos. Si otras extensiones ya realizan las mismas funciones, desactiva responsabilidades duplicadas para evitar mensajes repetidos y conflictos. Consulta nuestra selección de extensiones de VS Code para Python para crear un entorno más sencillo.

Una configuración habitual activa el formato al guardar y selecciona Ruff como formateador predeterminado para archivos Python. Aun así, conserva pyproject.toml como fuente principal de reglas. Las opciones que solo existen en el editor son difíciles de reproducir en una terminal, en otro equipo o en CI.

Ejecutar Ruff antes de cada commit

Las comprobaciones manuales funcionan al principio, pero es fácil olvidarlas. Añade un script, un hook de pre-commit o un comando de tareas. Una secuencia mínima de calidad puede ser:

ruff check .
ruff format --check .
pytest

Esta secuencia ejecuta el análisis estático, confirma el formato y corre las pruebas. Si una etapa falla, el hook o el pipeline debe detenerse. En un repositorio grande y existente, aplica primero el flujo a los archivos modificados y amplía la cobertura a medida que se corrige el código heredado.

Ruff en integración continua

En GitHub Actions, GitLab CI u otro servicio, instala las dependencias y ejecuta los mismos comandos utilizados localmente. No crees un conjunto de reglas totalmente diferente para el servidor. La integración continua aporta más valor cuando reproduce el flujo del desarrollador dentro de un entorno limpio.

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

Fija o limita versiones según la política del repositorio y actualiza de manera consciente. Una versión nueva puede añadir reglas, cambiar comportamientos de formato o exponer correcciones adicionales. Prueba la actualización en una rama y revisa las notas de versión antes de aplicarla a todos los proyectos.

Ruff, Black, Flake8 e isort: ¿cuál elegir?

Un proyecto estable no tiene que migrar solo porque exista una herramienta más reciente. Evalúa las dependencias de plugins, las convenciones actuales y el coste de cambiar muchos archivos. Ruff resulta atractivo en proyectos nuevos porque reduce la cantidad de configuraciones y dependencias. En proyectos antiguos, una migración por etapas suele ser más segura.

Errores comunes al adoptar Ruff

• Ejecutar --fix sin revisar: inspecciona el diff y corre las pruebas.
• Activar demasiadas reglas de inmediato: empieza con una base útil.
• Mantener dos formateadores activos: asigna un solo formateador a los mismos archivos.
• Configurar únicamente el editor: guarda las reglas dentro del repositorio.
• Analizar el entorno virtual: excluye .venv y las carpetas generadas.
• Usar supresiones amplias: especifica los códigos y documenta las excepciones.

Flujo recomendado para un proyecto nuevo

Crea el entorno virtual, instala Ruff y el ejecutor de pruebas, añade la configuración a pyproject.toml y realiza una primera comprobación. Después, formatea el repositorio, resuelve los avisos, confirma la base en Git y configura el editor. Por último, copia los mismos comandos al flujo de integración continua.

Así obtienes tres niveles de respuesta: el editor avisa de inmediato, la terminal ofrece una validación local explícita y el trabajo de CI protege la rama principal. Ruff se ocupa del trabajo mecánico repetitivo, mientras los revisores dedican más tiempo a arquitectura, seguridad, reglas de negocio y claridad.

Preguntas frecuentes

¿Ruff sustituye las pruebas automatizadas?

No. Ruff detecta patrones estáticos y ciertos errores, pero no confirma que la aplicación produzca el resultado correcto. Las pruebas unitarias y de integración validan el comportamiento.

¿Puedo usar Ruff solamente como linter?

Sí. Puedes ejecutar únicamente ruff check y conservar otro formateador. Configura las herramientas para que no dupliquen responsabilidades innecesariamente.

¿Ruff funciona en proyectos antiguos?

Sí, aunque conviene adoptarlo de forma gradual. Empieza con familias de reglas críticas, corrige una cantidad manejable de avisos y aumenta el rigor con el tiempo.

¿Debo ejecutar ruff check –fix en CI?

Normalmente CI debe verificar y fallar, no modificar archivos versionados. Las correcciones automáticas son más apropiadas en el entorno local o mediante un bot que proponga cambios revisables.

¿Dónde debo guardar la configuración?

Un archivo pyproject.toml en la raíz del repositorio es una opción práctica porque puede centralizar Ruff y otras herramientas del ecosistema Python.

Conclusión

Usar Ruff en Python convierte el lint, la organización de imports y el formato en una parte natural del desarrollo. Empieza con una configuración sencilla, revisa los cambios automáticos, guarda las reglas en el repositorio y ejecuta los mismos comandos en el editor, la terminal y el pipeline.

Ruff ofrece más valor como parte de un flujo de calidad completo. Los entornos virtuales aíslan dependencias, las pruebas protegen el comportamiento y la revisión humana evalúa decisiones que ninguna herramienta automática comprende por completo. Juntas, estas prácticas hacen que el código Python sea más consistente, mantenible y preparado para crecer.