Configuración de Ruff

Ruff es un linter y formateador basado en Rust que reemplaza a flake8, isort, pyupgrade y docenas de plugins en una única herramienta rápida. Es el linter predeterminado para los proyectos de Python 3.14.

Receta

uv add --group dev ruff

[tool.ruff]
line-length = 88
target-version = "py314"
 
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]

uv run ruff check .
uv run ruff format .

Cuándo usar esto:

Reemplazar flake8 + isort + autoflake + pyupgrade
Pasos de linting en CI que tardan más de unos pocos segundos
Nuevos proyectos de Python que necesitan una línea base de calidad sin configuración

Ejemplo Funcional

# pyproject.toml
[tool.ruff]
line-length = 88
target-version = "py314"
src = ["src", "tests"]
 
[tool.ruff.lint]
select = [
    "E",   # errores de pycodestyle
    "F",   # pyflakes
    "I",   # isort
    "UP",  # pyupgrade
    "B",   # bugbear
    "SIM", # simplify
]
ignore = ["E501"]  # la longitud de línea la maneja el formateador
 
[tool.ruff.lint.isort]
known-first-party = ["myapp"]
 
[tool.ruff.format]
quote-style = "double"

uv run ruff check . --fix
uv run ruff format .
uv run ruff check .   # verificar que esté limpio

Lo que esto demuestra:

Un único bloque de configuración reemplaza múltiples herramientas heredadas
select habilita categorías de reglas; ignore suprime códigos específicos
--fix corrige automáticamente violaciones seguras (importaciones, pyupgrade, algunos bugbear)
ruff format proporciona un formateo compatible con Black

Inmersión Profunda

Cómo Funciona

Ruff analiza el código fuente de Python con un analizador de Rust, típicamente 10-100 veces más rápido que flake8.
Los códigos de regla se mapean a plugins de flake8 (por ejemplo, B = bugbear, I = isort).
El formateador es compatible con el estilo de Black por defecto.
Una única binaria maneja el linting, formateo y ordenamiento de importaciones.

Conjuntos de Reglas Esenciales

Código	Fuente	Detecta
E, W	pycodestyle	Violaciones de estilo
F	pyflakes	Nombres indefinidos, importaciones no utilizadas
I	isort	Orden de importaciones
UP	pyupgrade	Sintaxis obsoleta
B	bugbear	Errores comunes
SIM	simplify	Código excesivamente complejo

Trampas Comunes

Ejecutar ruff sin configuración: los valores predeterminados pueden no coincidir con el estilo del equipo. Solución: confirma [tool.ruff] en pyproject.toml.
E501 en conflicto con el formateador: doble aplicación. Solución: ignora E501; deja que ruff format maneje la longitud de línea.
No establecer target-version: pyupgrade no sugerirá sintaxis de 3.14. Solución: establece target-version = "py314".
Faltan rutas src: la detección de importaciones de primera parte falla. Solución: establece src = ["src"] para proyectos con estructura src.
Reemplazo incremental de formateadores: Black y ruff format luchan en CI. Solución: elige un formateador; elimina el otro de CI.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
flake8 + plugins	Inversión en configuración heredada	Empezando de cero
pylint	Se necesita análisis semántico profundo	La velocidad es importante
Black solo	Solo formateo, sin linting	Quieres una sola herramienta

Preguntas Frecuentes

¿Ruff reemplaza a Black?

ruff format es compatible con Black. La mayoría de los equipos usan ruff tanto para linting como para formateo.

¿Cómo ignoro una línea?

# noqa: F401 en la línea, o # ruff: noqa para todas las reglas en esa línea.

¿Puede ruff corregir todas las violaciones?

Muchas reglas admiten --fix. Algunas (errores lógicos) requieren correcciones manuales.

¿Cómo agrego ruff a pre-commit?

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.9.0
  hooks:
    - id: ruff
      args: [--fix]
    - id: ruff-format

¿Cuál es la diferencia entre check y format?

ruff check realiza linting. ruff format formatea. Ejecuta ambos en CI.

¿Cómo veo todas las reglas habilitadas?

ruff linter lista los códigos de regla. ruff rule E501 explica una regla específica.

¿Ruff soporta monorepos?

Sí. Usa src y pyproject.toml por directorio o la configuración extend.

¿Puedo usar ruff con mypy?

Sí. Ruff detecta errores de estilo y obvios; mypy detecta errores de tipo. Ejecuta ambos.

¿Qué tan rápido es ruff comparado con flake8?

Típicamente 10-100 veces más rápido en bases de código medianas a grandes.

¿Qué versión debo fijar?

ruff>=0.9 según la pila del proyecto. Fija la versión exacta en rev de pre-commit.

Relacionado

Black / Ruff Format - detalles de formateo
Reglas Esenciales de Linting - recomendaciones de conjuntos de reglas
Hooks de pre-commit - integración de hooks de git
Linting en CI/CD - aplicación en pipelines

Versiones de la Pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.

Configuración de Ruff

Receta

uv add --group dev ruff

[tool.ruff]
line-length = 88
target-version = "py314"
 
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]

uv run ruff check .
uv run ruff format .

Cuándo usar esto:

Reemplazar flake8 + isort + autoflake + pyupgrade
Pasos de linting en CI que tardan más de unos pocos segundos
Nuevos proyectos de Python que necesitan una línea base de calidad sin configuración

Ejemplo Funcional

# pyproject.toml
[tool.ruff]
line-length = 88
target-version = "py314"
src = ["src", "tests"]
 
[tool.ruff.lint]
select = [
    "E",   # errores de pycodestyle
    "F",   # pyflakes
    "I",   # isort
    "UP",  # pyupgrade
    "B",   # bugbear
    "SIM", # simplify
]
ignore = ["E501"]  # la longitud de línea la maneja el formateador
 
[tool.ruff.lint.isort]
known-first-party = ["myapp"]
 
[tool.ruff.format]
quote-style = "double"

uv run ruff check . --fix
uv run ruff format .
uv run ruff check .   # verificar que esté limpio

Lo que esto demuestra:

Un único bloque de configuración reemplaza múltiples herramientas heredadas
select habilita categorías de reglas; ignore suprime códigos específicos
--fix corrige automáticamente violaciones seguras (importaciones, pyupgrade, algunos bugbear)
ruff format proporciona un formateo compatible con Black

Inmersión Profunda

Cómo Funciona

Ruff analiza el código fuente de Python con un analizador de Rust, típicamente 10-100 veces más rápido que flake8.
Los códigos de regla se mapean a plugins de flake8 (por ejemplo, B = bugbear, I = isort).
El formateador es compatible con el estilo de Black por defecto.
Una única binaria maneja el linting, formateo y ordenamiento de importaciones.

Conjuntos de Reglas Esenciales

Código	Fuente	Detecta
E, W	pycodestyle	Violaciones de estilo
F	pyflakes	Nombres indefinidos, importaciones no utilizadas
I	isort	Orden de importaciones
UP	pyupgrade	Sintaxis obsoleta
B	bugbear	Errores comunes
SIM	simplify	Código excesivamente complejo

Trampas Comunes

Ejecutar ruff sin configuración: los valores predeterminados pueden no coincidir con el estilo del equipo. Solución: confirma [tool.ruff] en pyproject.toml.
E501 en conflicto con el formateador: doble aplicación. Solución: ignora E501; deja que ruff format maneje la longitud de línea.
No establecer target-version: pyupgrade no sugerirá sintaxis de 3.14. Solución: establece target-version = "py314".
Faltan rutas src: la detección de importaciones de primera parte falla. Solución: establece src = ["src"] para proyectos con estructura src.
Reemplazo incremental de formateadores: Black y ruff format luchan en CI. Solución: elige un formateador; elimina el otro de CI.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
flake8 + plugins	Inversión en configuración heredada	Empezando de cero
pylint	Se necesita análisis semántico profundo	La velocidad es importante
Black solo	Solo formateo, sin linting	Quieres una sola herramienta

Preguntas Frecuentes

¿Ruff reemplaza a Black?

ruff format es compatible con Black. La mayoría de los equipos usan ruff tanto para linting como para formateo.

¿Cómo ignoro una línea?

# noqa: F401 en la línea, o # ruff: noqa para todas las reglas en esa línea.

¿Puede ruff corregir todas las violaciones?

Muchas reglas admiten --fix. Algunas (errores lógicos) requieren correcciones manuales.

¿Cómo agrego ruff a pre-commit?

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.9.0
  hooks:
    - id: ruff
      args: [--fix]
    - id: ruff-format

¿Cuál es la diferencia entre check y format?

ruff check realiza linting. ruff format formatea. Ejecuta ambos en CI.

¿Cómo veo todas las reglas habilitadas?

ruff linter lista los códigos de regla. ruff rule E501 explica una regla específica.

¿Ruff soporta monorepos?

Sí. Usa src y pyproject.toml por directorio o la configuración extend.

¿Puedo usar ruff con mypy?

Sí. Ruff detecta errores de estilo y obvios; mypy detecta errores de tipo. Ejecuta ambos.

¿Qué tan rápido es ruff comparado con flake8?

Típicamente 10-100 veces más rápido en bases de código medianas a grandes.

¿Qué versión debo fijar?

ruff>=0.9 según la pila del proyecto. Fija la versión exacta en rev de pre-commit.

Relacionado

Black / Ruff Format - detalles de formateo
Reglas Esenciales de Linting - recomendaciones de conjuntos de reglas
Hooks de pre-commit - integración de hooks de git
Linting en CI/CD - aplicación en pipelines

Versiones de la Pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.

Configuración de Ruff

Buscar en la documentación

Configuración de Ruff