Django Folder Structure

📁 What is Django Folder Structure?

Django's folder structure organizes your project into logical components. Understanding this structure helps you navigate projects efficiently and follow Django's best practices for building scalable web applications.

mysite/
    manage.py
    mysite/
    blog/
    users/

Key Folders & Files

⚙️

Project Folder

Contains settings and configurations

mysite/
  settings.py
  urls.py

📦

App Folders

Individual app components

blog/
  models.py
  views.py

🎨

Templates

HTML template files

templates/
  base.html
  home.html

💎

Static Files

CSS, JavaScript, images

static/
  css/
  js/
  images/

🔹 Complete Project Structure

Here's a typical Django project structure with all essential folders and files organized for a real-world application:

mysite/                    # Root project directory
│
├── manage.py              # Command-line utility
│
├── mysite/                # Project configuration folder
│   ├── __init__.py        # Python package marker
│   ├── settings.py        # Project settings
│   ├── urls.py            # Main URL configuration
│   ├── asgi.py            # ASGI configuration
│   └── wsgi.py            # WSGI configuration
│
├── blog/                  # Blog app
│   ├── migrations/        # Database migrations
│   │   └── __init__.py
│   ├── __init__.py
│   ├── admin.py           # Admin interface
│   ├── apps.py            # App configuration
│   ├── models.py          # Data models
│   ├── tests.py           # Unit tests
│   ├── views.py           # View functions
│   └── urls.py            # App URLs
│
├── templates/             # HTML templates
│   ├── base.html
│   └── blog/
│       └── post_list.html
│
├── static/                # Static files
│   ├── css/
│   │   └── style.css
│   ├── js/
│   │   └── script.js
│   └── images/
│
└── media/                 # User-uploaded files
    └── uploads/

🔹 Project Configuration Files

The main project folder contains critical configuration files that control how Django operates:

🔸 settings.py

# mysite/settings.py

DEBUG = True
ALLOWED_HOSTS = []

INSTALLED_APPS = [
    'django.contrib.admin',
    'blog',
]

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

🔸 urls.py

# mysite/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('blog/', include('blog.urls')),
]

🔹 App Structure Explained

Each Django app follows a consistent structure with specific files for different purposes:

📦 blog/ (App Folder)

models.py: Database table definitions
views.py: Request handling logic
urls.py: URL patterns for the app
admin.py: Admin panel configuration
apps.py: App configuration class
tests.py: Test cases for the app
migrations/: Database schema changes

# blog/models.py
from django.db import models

class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()

# blog/views.py
from django.shortcuts import render

def post_list(request):
    return render(request, 'blog/post_list.html')

# blog/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.post_list, name='post_list'),
]

🔹 Templates Folder

Templates contain HTML files that Django renders with dynamic data. Organize templates by app for better maintainability:

templates/
├── base.html              # Base template
├── blog/
│   ├── post_list.html     # Blog post list
│   └── post_detail.html   # Single post view
└── users/
    ├── login.html         # Login page
    └── profile.html       # User profile

<!-- templates/base.html -->
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}My Site{% endblock %}</title>
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>

<!-- templates/blog/post_list.html -->
{% extends 'base.html' %}

{% block content %}
    <h1>Blog Posts</h1>
    {% for post in posts %}
        <h2>{{ post.title }}</h2>
    {% endfor %}
{% endblock %}

🔹 Static Files Organization

Static files include CSS, JavaScript, and images. Django collects these files for production deployment:

static/
├── css/
│   ├── style.css
│   └── blog.css
├── js/
│   ├── main.js
│   └── utils.js
└── images/
    ├── logo.png
    └── banner.jpg

# settings.py

STATIC_URL = '/static/'
STATICFILES_DIRS = [BASE_DIR / 'static']
STATIC_ROOT = BASE_DIR / 'staticfiles'

<!-- Using static files in templates -->
{% load static %}

<link rel="stylesheet" href="{% static 'css/style.css' %}">
<img src="{% static 'images/logo.png' %}" alt="Logo">

🔹 Media Files

Media files are user-uploaded content like profile pictures or documents. Configure Django to handle these files properly:

# settings.py

MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

# mysite/urls.py
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... your patterns
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, 
                         document_root=settings.MEDIA_ROOT)