Django se compromete con la estabilidad de la API y la compatibilidad hacia adelante. En pocas palabras, esto significa que el código que desarrollas contra una versión de Django continuará funcionando con futuras versiones. Es posible que debas realizar cambios menores cuando actualices la versión de Django utilizada por tu proyecto: consulta la sección «Cambios no compatibles con lo anterior» del nota de liberación para la versión o versiones a las que estás actualizando.
Al mismo tiempo que prioriza la estabilidad de la API, Django también se compromete con la mejora continua, junto con el objetivo de «una forma de hacerlo» (eventualmente) en las APIs que proporcionamos. Esto significa que cuando descubrimos formas claramente superiores de hacer las cosas, eliminaremos y eventualmente eliminaremos los métodos antiguos. Nuestro objetivo es proporcionar un marco web moderno, confiable y de alta calidad que fomente buenas prácticas en todos los proyectos que lo utilicen. Al utilizar mejoras incrementales, intentamos evitar tanto la estagnación como las grandes actualizaciones no compatibles.
En este contexto, estable significa:
Todos los APIs públicos (todo en esta documentación) no se moverán ni se renombrarán sin proporcionar alias compatibles hacia atrás.
Si se agregan nuevas características a estos APIs – lo cual es posible – no romperán ni cambiarán el significado de los métodos existentes. En otras palabras, «estable» no (necesariamente) significa «completo».
Si por alguna razón un API declarado estable debe eliminarse o reemplazarse, se declarará obsoleto pero permanecerá en la API durante al menos dos versiones de características. Se emitirán advertencias cuando el método obsoleto se invoque.
Consulta Liberaciones oficiales para obtener más detalles sobre cómo funciona el esquema de numeración de versiones de Django y cómo se desprecian las características.
Solo romperemos la compatibilidad hacia atrás de estas APIs sin un proceso de despreciable si una falla o agujero de seguridad lo hace completamente inevitable.
En general, todo lo cubierto en la documentación – con la excepción de cualquier cosa que se encuentre en el área internos – se considera estable.
Hay unas pocas excepciones a esta promesa de estabilidad y compatibilidad hacia atrás.
Si nos damos cuenta de un problema de seguridad – con suerte gracias a alguien que sigue nuestra política de informes de seguridad – haremos todo lo necesario para solucionarlo. Esto podría significar romper la compatibilidad hacia atrás; la seguridad tiene prioridad sobre la garantía de compatibilidad.
Algunas APIs están explícitamente marcadas como «internas» de varias maneras:
Algunas documentación se refiere a los internos y los menciona como tales. Si la documentación dice que algo es interno, reservamos el derecho a cambiarlo.
Las funciones, métodos y otros objetos prefijados con un guión subrayado (_). Esto es la forma estándar de Python para indicar que algo es privado; si cualquier método comienza con un solo _, es una API interna.
may 31, 2026