Structure d'un projet Django

Ce que Django génère au démarrage

Quand vous lancez django-admin startproject monprojet, Django crée immédiatement une arborescence bien définie. Chaque fichier a un rôle précis — rien n'est superflu. Voici la structure complète d'un projet vide, avant même la création d'une application :

monprojet/               # Dossier racine — simple conteneur, renommable
    manage.py            # Outil de commandes Django
    monprojet/           # Paquet Python du projet — ne pas renommer
        __init__.py      # Marque ce dossier comme module Python
        settings.py      # Configuration centrale du projet
        urls.py          # Routage URL principal
        wsgi.py          # Point d'entrée WSGI (production)
        asgi.py          # Point d'entrée ASGI (async, WebSockets)

Le dossier externe porte le nom que vous avez choisi — c'est juste un conteneur. Le dossier interne du même nom est le vrai paquet Python du projet : Django l'importe constamment, ne le renommez pas sans mettre à jour toutes les références.

Les fichiers du projet — détail

manage.py

manage.py est l'outil de travail quotidien. Vous ne le modifiez jamais, mais vous l'utilisez pour presque tout : démarrer le serveur, créer des migrations, lancer les tests, ouvrir le shell, créer un super-utilisateur. Il charge automatiquement la configuration de votre projet avant chaque commande.

# Exemples de commandes courantes via manage.py
python manage.py runserver          # Lance le serveur de développement
python manage.py makemigrations     # Génère les fichiers de migration
python manage.py migrate            # Applique les migrations en base
python manage.py createsuperuser    # Crée un compte administrateur
python manage.py shell              # Ouvre le shell Python avec le projet chargé
python manage.py test               # Lance les tests unitaires

settings.py

settings.py est le fichier de configuration central. Tout ce qui conditionne le comportement global de votre application s'y trouve : connexion à la base de données, applications installées, clé secrète, fuseau horaire, langue, répertoires des templates, chemins des fichiers statiques. C'est le premier fichier que vous ouvrirez après avoir créé un projet.

Parmi les paramètres essentiels à connaître :

# monprojet/settings.py — extraits clés

SECRET_KEY = 'votre-clé-secrète'   # Ne jamais la publier
DEBUG = True                        # False impérativement en production

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'monapp',                        # Vos applications déclarées ici
]

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

LANGUAGE_CODE = 'fr-fr'
TIME_ZONE = 'Europe/Paris'

urls.py

urls.py est le routeur principal du projet. Il contient la liste urlpatterns qui associe chaque URL à une vue ou délègue à un fichier urls.py d'application via include(). Django le lit à chaque requête pour décider quelle vue appeler.

wsgi.py et asgi.py

wsgi.py est le point d'entrée pour les serveurs web de production synchrones comme Gunicorn ou uWSGI. asgi.py est son équivalent asynchrone, introduit dans Django 3.0 pour les connexions WebSocket et les vues async. En développement avec runserver, vous n'avez pas à toucher à ces fichiers.

Structure d'une application Django

Un projet peut contenir plusieurs applications. Chaque application créée avec python manage.py startapp monapp génère sa propre arborescence :

monapp/
    __init__.py       # Module Python
    admin.py          # Enregistrement des modèles dans l'interface admin
    apps.py           # Configuration de l'application
    models.py         # Définition des tables (classes Python → SQL)
    views.py          # Logique : reçoit les requêtes, renvoie les réponses
    tests.py          # Tests unitaires
    urls.py           # À créer manuellement — routage interne à l'app
    migrations/       # Fichiers générés par makemigrations
        __init__.py
    templates/        # À créer manuellement — fichiers HTML
    static/           # À créer manuellement — CSS, JS, images

Trois éléments sont à créer manuellement après startapp — Django ne les génère pas automatiquement :

urls.py — le routeur interne à l'application. Sans lui, les URLs de l'application ne sont pas accessibles.

templates/ — le dossier des fichiers HTML. Django le cherche automatiquement si l'application est dans INSTALLED_APPS.

static/ — le dossier des fichiers statiques (CSS, JavaScript, images).

Vue d'ensemble d'un projet avec une application

Voici à quoi ressemble la structure complète d'un projet Django avec une application membres :

monprojet/
    manage.py
    db.sqlite3                   # Base de données SQLite (développement)
    monprojet/
        __init__.py
        settings.py
        urls.py
        wsgi.py
        asgi.py
    membres/
        __init__.py
        admin.py
        apps.py
        models.py
        views.py
        urls.py
        tests.py
        migrations/
            __init__.py
            0001_initial.py      # Générée par makemigrations
        templates/
            index.html
            ajout.html
            update.html
        static/
            mon_style.css
            mon_script.js

Cette organisation est celle que vous retrouverez dans tout projet Django, qu'il soit personnel ou professionnel. Django est très conventionnel sur ce point — respecter cette structure permet à n'importe quel développeur Django de se repérer immédiatement dans votre code.

Par carabde | Mis à jour le 05 mai 2025