--- title: "Les réglages de Django" version: 5.2 locale: fr source: https://docs.djangoproject.com/fr/5.2/topics/settings/ canonical: https://djangodocs.dev/fr/5.2/topics/settings/ --- # Les réglages de Django Un fichier de réglages Django contient toute la configuration de votre installation de Django. Ce document explique le fonctionnement des réglages et quels sont les réglages disponibles. ## Principes de base Un fichier de réglages n’est qu’un module Python avec des variables de niveau module. Voici quelques exemples de réglages : ``` ALLOWED_HOSTS = ["www.example.com"] DEBUG = False DEFAULT_FROM_EMAIL = "webmaster@example.com" ``` > **Note** > > Si vous définissez [`DEBUG`](/fr/5.2/ref/settings/#std-setting-DEBUG) à `False`, vous devez également définir correctement le réglage [`ALLOWED_HOSTS`](/fr/5.2/ref/settings/#std-setting-ALLOWED_HOSTS). Comme un fichier de réglages est un module Python, les points suivants s’appliquent : - Il n’accepte pas les erreurs de syntaxe Python. - Il peut attribuer des valeurs de réglages dynamiques avec la syntaxe Python habituelle. Par exemple : ``` MY_SETTING = [str(i) for i in range(30)] ``` - Il peut importer des valeurs provenant d’autres fichiers de réglages. ## Définition du fichier de réglages #### `DJANGO_SETTINGS_MODULE` Quand vous utilisez Django, vous devez lui indiquer le fichier de réglages qu’il doit utiliser. Vous pouvez le faire par une variable d’environnement, [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE). La valeur de [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) doit respecter la syntaxe des chemins Python, par ex. `mysite.settings`. Notez que le module de réglages doit se trouver dans le chemin système [`sys.path`](https://docs.python.org/3/library/sys.html#sys.path) de Python. ### L’utilitaire `django-admin` Quand vous utilisez [django-admin](/fr/5.2/ref/django-admin/), vous pouvez soit définir une seule fois la variable d’environnement, soit lui transmettre explicitement le module de réglages à chaque lancement de la commande. Exemple (shell Unix bash) : ```shell export DJANGO_SETTINGS_MODULE=mysite.settings django-admin runserver ``` Exemple (shell Windows) : ```doscon set DJANGO_SETTINGS_MODULE=mysite.settings django-admin runserver ``` Utilisez le paramètre de ligne de commande `--settings` pour indiquer manuellement le fichier de réglages : ```shell django-admin runserver --settings=mysite.settings ``` ### Sur le serveur (`mod_wsgi`) Dans l’environnement de production de votre serveur, vous devrez indiquer à votre application WSGI quel fichier de réglages il doit utiliser. Faites-le avec `os.environ`: ``` import os os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings" ``` Lisez la [documentation Django de mod\_wsgi](/fr/5.2/howto/deployment/wsgi/modwsgi/) pour plus d’informations ainsi que d’autres éléments communs à toute application WSGI Django. ## Réglages par défaut Un fichier de réglages Django n’a aucune obligation de définir des réglages s’il n’y a pas de besoins avérés. Chaque réglage possède une valeur par défaut logique. Ces valeurs par défaut se trouvent dans le module [django/conf/global\_settings.py](https://github.com/django/django/blob/stable/5.2.x/django/conf/global_settings.py). Voici l’algorithme utilisé par Django pour compiler les réglages : - Charger les réglages de `global_settings.py`. - Charger les réglages du fichier de réglages en vigueur, surchargeant les réglages globaux si nécessaire. Notez qu’un fichier de réglages ne doit *pas* importer `global_settings`, car ce serait redondant. ### Vision des réglages modifiés La commande `python manage.py diffsettings` affiche les différences entre le fichier de réglages actuel et les réglages par défaut de Django. Pour en savoir plus, lisez la documentation de [`diffsettings`](/fr/5.2/ref/django-admin/#django-admin-diffsettings). ## Utilisation des réglages dans le code Python Dans vos applications Django, utilisez les réglages en important l’objet `django.conf.settings`. Exemple : ``` from django.conf import settings if settings.DEBUG: # Do something ... ``` Notez que `django.conf.settings` n’est pas un module, c’est un objet. L’importation de réglages individuels n’est donc pas possible : ``` from django.conf.settings import DEBUG # This won't work. ``` Notez également que votre code ne doit *pas* importer ni de `global_settings`, ni de votre propre fichier de réglages. `django.conf.settings` est une abstraction du concept de réglages par défaut et de réglages spécifiques par site ; il présente une interface unifiée. Il découple aussi le code qui utilise les réglages de l’emplacement de vos réglages. ## Modification des réglages en cours d’exécution Vous ne devriez pas modifier les réglages de vos applications durant leur exécution. Par exemple, ne faites pas ceci dans une vue : ``` from django.conf import settings settings.DEBUG = True # Don't do this! ``` Le seul endroit où des réglages doivent recevoir des valeurs est le fichier des réglages. ## Sécurité Dans la mesure où un fichier de réglages contient des informations sensibles comme des mots de passe de base de données, vous devez faire tout votre possible pour limiter l’accès à ces fichiers. Par exemple, modifiez les permissions du fichier pour que seuls vous et le serveur web puissiez le lire. C’est particulièrement important dans le contexte d’un environnement d’hébergement partagé. ## Réglages disponibles Pour une liste complète des réglages disponibles, consultez la [référence des réglages](/fr/5.2/ref/settings/). ## Création de ses propres réglages Rien ne vous empêche de créer vos propres réglages pour vos propres applications Django, mais suivez ces lignes de conduite : - Les noms des réglages doivent être tout en majuscules. - Ne réinventez pas un réglage existant. Pour les réglages qui sont de type liste, Django utilise lui-même des listes Python, mais ce n’est qu’une convention. ## Utilisation des réglages sans définir [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) Dans certains cas, il peut être souhaitable de ne pas tenir compte de la variable d’environnement [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE). Par exemple, si vous utilisez le système de gabarits pour lui-même, il n’est probablement pas utile de configurer une variable d’environnement pointant vers un module de réglages. Dans ces situations, vous pouvez configurer manuellement les réglages de Django. Faites-le en appelant : #### `django.conf.settings.configure(default_settings, **settings)` Exemple : ``` from django.conf import settings settings.configure(DEBUG=True) ``` Vous pouvez transmettre autant de paramètres que nécessaire à `configure()`, sachant que chaque paramètre nommé constituera un réglage avec sa valeur. Chaque nom de paramètre devrait être entièrement en majuscules et correspondre à l’un des paramètres existants. Si un réglage particulier n’est pas transmis à `configure()` et qu’il est requis plus loin dans le code, Django utilise alors la valeur par défaut du réglage. La configuration de Django de cette manière est surtout nécessaire (et même recommandée) lorsque vous utilisez une partie de l’infrastructure Django dans une application plus vaste. En conséquence, quand Django est configuré par `settings.configure()`, il ne fera aucune modification aux variables d’environnement du processus (consultez la documentation de [`TIME_ZONE`](/fr/5.2/ref/settings/#std-setting-TIME_ZONE) pour savoir pourquoi cela se passe normalement). Django suppose alors que vous avez déjà le contrôle complet de votre environnement. ### Réglages par défaut personnalisés Si vous aimeriez que des valeurs par défaut proviennent d’endroits différents de `django.conf.global_settings`, vous pouvez transmettre un module ou une classe responsable de fournir les valeurs par défaut dans le paramètre `default_settings` (ou comme premier paramètre positionnel) dans l’appel à `configure()`. Dans cet exemple, les réglages par défaut proviennent de `myapp_defaults` et le paramètre [`DEBUG`](/fr/5.2/ref/settings/#std-setting-DEBUG) est défini à `True`, quelle que soit sa valeur dans `myapp_defaults`: ``` from django.conf import settings from myapp import myapp_defaults settings.configure(default_settings=myapp_defaults, DEBUG=True) ``` L’exemple suivant qui place `myapp_defaults` comme paramètre positionnel est équivalent : ``` settings.configure(myapp_defaults, DEBUG=True) ``` Normalement, il n’est pas nécessaire de surcharger les valeurs par défaut de cette manière. Les valeurs par défaut de Django sont suffisamment éprouvées pour pouvoir les utiliser avec confiance. Sachez que lorsque vous transmettez un nouveau module de valeurs par défaut, il *remplace* entièrement les valeurs par défaut de Django, il est donc indispensable de fournir des valeurs pour chaque réglage potentiellement utilisé dans le code que vous importez. Parcourez `django.conf.settings.global_settings` pour voir la liste complète. ### Nécessité de `configure()` ou de [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) Si vous ne définissez pas la variable d’environnement [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE), vous *devez* appeler `configure()` avant que du code se mette à lire des réglages. Si vous ne définissez pas [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) et n’appelez pas `configure()`, Django lèvera une exception `ImportError` lors du premier accès à un réglage. Si vous définissez [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE), puis vous accédez à des valeurs de réglages d’une manière ou d’une autre, *puis* vous appelez `configure()`, Django lèvera une exception `RuntimeError` indiquant que les réglages ont déjà été configurés. Il existe une propriété pour ce cas de figure : #### `django.conf.settings.configured` Par exemple : ``` from django.conf import settings if not settings.configured: settings.configure(myapp_defaults, DEBUG=True) ``` Il est également erroné d’appeler `configure()` plus d’une fois, ou d’appeler `configure()` après qu’au moins un réglage ait été lu. En conclusion : utilisez soit `configure()`, soit [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE), mais jamais les deux et toujours au moins un des deux. ### Appel obligatoire de `django.setup()` pour utiliser Django de manière « indépendante » Si vous utilisez des composants de Django de manière indépendante, par exemple en écrivant un script Python qui charge certains gabarits Django et les produit, ou en utilisant l’ORM pour récupérer certaines données, une étape supplémentaire est nécessaire en plus de la configuration des réglages. Après avoir soit défini [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) ou appelé `configure()`, vous devrez appeler [`django.setup()`](/fr/5.2/ref/applications/#django.setup) pour charger les réglages et remplir le registre des applications de Django. Par exemple : ``` 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 ``` Notez que l’appel à `django.setup()` n’est nécessaire que si votre code est réellement indépendant. Lorsqu’il est appelé par un serveur web ou par l’intermédiaire de [django-admin](/fr/5.2/ref/django-admin/), Django se charge de procéder à cette initialisation. > **django.setup() ne peut être appelée qu’une seule fois.** > > Ainsi, évitez de placer de la logique applicative réutilisable dans des scripts autonomes pour ne pas devoir importer le script depuis un autre endroit de votre application. Si c’est inévitable, placez l’appel à `django.setup()` à l’intérieur d’un bloc `if`: > > ``` > if __name__ == "__main__": > import django > > django.setup() > ``` > **See also** > > **[La référence des réglages](/fr/5.2/ref/settings/)** > > Contient une liste complète des réglages de Django et de ses applications « contrib ».