Un archivo de configuración de Django contiene toda la configuración de tu instalación de Django. Este documento explica cómo funcionan las configuraciones y cuáles están disponibles.
Un archivo de configuración es simplemente un módulo de Python con variables de nivel de módulo.
Aquí tienes un par de configuraciones de ejemplo:
ALLOWED_HOSTS = ["www.example.com"]
DEBUG = False
DEFAULT_FROM_EMAIL = "webmaster@example.com"
Nota
Si estableces DEBUG en False, también debes configurar correctamente la configuración de ALLOWED_HOSTS.
Porque un archivo de configuración es un módulo de Python, se aplican las siguientes reglas:
No permite errores de sintaxis en Python.
Puede asignar configuraciones dinámicamente utilizando la sintaxis normal de Python. Por ejemplo:
MY_SETTING = [str(i) for i in range(30)]
Puede importar valores desde otros archivos de configuración.
Cuando utilizas Django, debes indicarle cuál es la configuración que estás utilizando. Hazlo estableciendo una variable de entorno, DJANGO_SETTINGS_MODULE.
El valor de DJANGO_SETTINGS_MODULE debe estar en sintaxis de ruta del sistema Python, por ejemplo mysite.settings. Ten en cuenta que el módulo de configuración debe estar en la lista de rutas del sistema Python: sys.path.
django-admin¶Cuando utilizas django-admin, puedes establecer la variable de entorno una vez o pasar explícitamente el módulo de configuración cada vez que ejecutes la utilidad.
Ejemplo (shell Unix Bash):
export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
Ejemplo (shell Windows):
set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
Usa la opción de línea de comandos –settings para especificar manualmente las configuraciones:
django-admin runserver --settings=mysite.settings
mod_wsgi)¶En tu entorno de servidor en vivo, necesitarás decirle a tu aplicación WSGI qué archivo de configuración utilizar. Hazlo con os.environ:
import os
os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"
Lee la documentación de Django sobre mod_wsgi <howto/deployment/wsgi/modwsgi> para obtener más información y otros elementos comunes a una aplicación WSGI de Django.
Un archivo de configuración de Django no necesita definir ninguna configuración si no es necesario. Cada configuración tiene un valor por defecto sensato. Estos valores por defecto viven en el módulo django/conf/global_settings.py.
Aquí está el algoritmo que utiliza Django para compilar configuraciones:
Carga las configuraciones de global_settings.py.
Carga las configuraciones del archivo de configuración especificado, sobreescribiendo las configuraciones globales según sea necesario.
Ten en cuenta que un archivo de configuración no debe importar desde global_settings, porque eso es redundante.
La orden python manage.py diffsettings muestra las diferencias entre el archivo de configuración actual y la configuración por defecto de Django.
Para más información, consulta la documentación sobre diffsettings.
En tus aplicaciones Django, utiliza las configuraciones importando el objeto django.conf.settings. Ejemplo:
from django.conf import settings
if settings.DEBUG:
# Do something
...
Ten en cuenta que django.conf.settings no es un módulo – es un objeto. Por lo tanto, la importación de configuraciones individuales no es posible:
from django.conf.settings import DEBUG # This won't work.
También ten en cuenta que tu código no debe importar desde ni global_settings ni tu propio archivo de configuración. django.conf.settings abstracta los conceptos de configuraciones por defecto y configuraciones específicas del sitio; presenta una sola interfaz. También desacopla el código que utiliza configuraciones de la ubicación de tus configuraciones.
No debes alterar configuraciones en tus aplicaciones en tiempo de ejecución. Por ejemplo, no hagas esto en una vista:
from django.conf import settings
settings.DEBUG = True # Don't do this!
El único lugar donde debes asignar a configuraciones es en un archivo de configuración.
Porque un archivo de configuración contiene información sensible, como la contraseña de la base de datos, debes hacer todo lo posible para limitar el acceso a él. Por ejemplo, cambia las permisos del archivo para que solo tú y el usuario de tu servidor web puedan leerlo. Esto es especialmente importante en un entorno de alojamiento compartido.
Para obtener una lista completa de configuraciones disponibles, consulta la referencia de configuración.
No hay nada que te impida crear tu propia configuración para tus propias aplicaciones Django, pero sigue estos consejos:
Los nombres de las configuraciones deben ser todos mayúsculos.
No reinventes una configuración ya existente.
Para configuraciones que son secuencias, Django utiliza listas, pero esto es solo una convención.
DJANGO_SETTINGS_MODULE¶Los textos traducidos son:
En estos casos, puede configurar manualmente las configuraciones de Django. Haga esto llamando a:
Ejemplo:
from django.conf import settings
settings.configure(DEBUG=True)
Pasa configure() con tantos argumentos clave como desee, con cada argumento clave representando una configuración y su valor. Cada nombre de argumento debe ser todo en mayúsculas, con el mismo nombre que las configuraciones descritas anteriormente. Si una configuración particular no se pasa a configure() y es necesaria en algún momento posterior, Django utilizará el valor predeterminado de la configuración.
Configurar a Django de esta manera es principalmente necesario – e incluso recomendado – cuando está utilizando una pieza del marco dentro de una aplicación más grande.
Consecuentemente, cuando se configura mediante settings.configure(), Django no realizará ninguna modificación en las variables de entorno del proceso (consulte la documentación de TIME_ZONE para saber por qué esto normalmente ocurriría). Se asume que ya tiene control total sobre su entorno en estos casos.
Si desea que los valores predeterminados provengan de algo más que django.conf.global_settings, puede pasar un módulo o clase que proporciona las configuraciones predeterminadas como el argumento default_settings (o como el primer argumento posicional) en la llamada a configure().
En este ejemplo, las configuraciones predeterminadas se toman de myapp_defaults, y la configuración DEBUG está establecida en True, independientemente de su valor en myapp_defaults:
from django.conf import settings
from myapp import myapp_defaults
settings.configure(default_settings=myapp_defaults, DEBUG=True)
El siguiente ejemplo, que utiliza myapp_defaults como argumento posicional, es equivalente:
settings.configure(myapp_defaults, DEBUG=True)
Normalmente, no necesitará sobrescribir los valores predeterminados de esta manera. Los valores predeterminados de Django son lo suficientemente tibios como para que pueda utilizarlos con seguridad. Ten en cuenta que si pasa un nuevo módulo de configuraciones predeterminadas, reemplaza completamente los valores predeterminados de Django, por lo que debe especificar un valor para cada posible configuración que se utilice en el código que está importando. Consulte django.conf.settings.global_settings para obtener la lista completa.
configure() o DJANGO_SETTINGS_MODULE es requerido.¶Si no estás estableciendo la variable de entorno DJANGO_SETTINGS_MODULE, debes llamar a configure() en algún punto antes de usar cualquier código que lea configuraciones.
Si no estableces DJANGO_SETTINGS_MODULE y no llamas a configure(), Django lanzará una excepción ImportError la primera vez que se acceda a una configuración.
Si estableces DJANGO_SETTINGS_MODULE, accedes a valores de configuraciones de alguna manera, luego llama a configure(), Django lanzará un error RuntimeError indicando que las configuraciones ya han sido configuradas. Hay una propiedad para este propósito:
Por ejemplo:
from django.conf import settings
if not settings.configured:
settings.configure(myapp_defaults, DEBUG=True)
También es un error llamar a configure() más de una vez, o llamar a configure() después de que alguna configuración haya sido accedida.
Se reduce a esto: Utiliza exactamente uno de los dos, configure() o DJANGO_SETTINGS_MODULE. Ni ambos ni ninguno.
django.setup() es requerido para el uso «independiente» de Django¶Si estás utilizando componentes de Django «independientes» – por ejemplo, escribiendo un script Python que carga plantillas Django y las renderiza, o utiliza ORM para obtener algunos datos – hay otro paso adicional al configurar configuraciones.
Después de haber establecido DJANGO_SETTINGS_MODULE o llamado a configure(), necesitarás llamar a django.setup() para cargar tus configuraciones y poblar el registro de aplicaciones de Django. Por ejemplo:
import django
from django.conf import settings
from myapp import myapp_defaults
settings.configure(default_settings=myapp_defaults, DEBUG=True)
django.setup()
# Now this script or any imported module can use any part of Django it needs.
from myapp import models
Ten en cuenta que llamar a django.setup() es solo necesario si tu código es verdaderamente independiente. Cuando se invoca por tu servidor web, o a través de django-admin, Django manejará esto por ti.
django.setup() solo se puede llamar una vez.
Por lo tanto, evita poner lógica de aplicación reutilizable en scripts independientes para que puedas importar desde el script en otras partes de tu aplicación. Si no puedes evitarlo, coloca la llamada a django.setup() dentro de un bloque if:
if __name__ == "__main__":
import django
django.setup()
Ver también
Contiene la lista completa de configuraciones de aplicaciones core y contrib.
may 31, 2026