When you create a new Django project for the first time, Django automatically generates a set of files and folders. For beginners, this structure may look confusing at first. However, each file has a clear role, and understanding this organization is very important if you want to work comfortably with Django.
In this tutorial, you will learn the purpose of the main files and folders in a Django project, how they work together, and why Django organizes projects in this way. By the end, you will be able to navigate a Django project with confidence.
A Django project is not just a collection of random Python files. It follows a structured and organized layout.
This structure helps developers:
A well-understood structure is the foundation for writing better Django code.
When you run a command like:
django-admin startproject config .Django creates a project structure similar to this:
my_django_project/
│
├── manage.py
├── config/
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.pyIf later you create an app, the structure will become larger, but for now let us focus on these core files.
The root folder is the main project directory. It contains the overall Django project and all the files related to it.
Example:
my_django_project/This folder may also contain:
It is the top-level folder where you usually run Django commands.
manage.pyOne of the first files you will notice is:
manage.pyThis file is very important because it allows you to interact with your Django project from the command line.
manage.py doesIt acts as a command-line utility for performing project tasks such as:
manage.pypython manage.py runserver
python manage.py migrate
python manage.py startapp blogWithout manage.py, you would have to use more complicated commands. It simplifies project management.
You will use this file in almost every Django project.
Inside the root folder, Django creates another folder with the project name, for example:
config/This folder is the actual Python package for your Django project. It contains the main configuration files.
This folder usually includes:
__init__.pysettings.pyurls.pyasgi.pywsgi.pyThese files define how the project behaves.
__init__.pyThis file is usually empty:
config/__init__.pyIts role is to tell Python that this folder should be treated as a Python package.
In most beginner projects, you do not need to modify it.
Python uses __init__.py to recognize importable packages. Even if it is empty, it is still important.
settings.pyThis is one of the most important files in a Django project:
config/settings.pyIt contains the global configuration of your project.
settings.py controlsIt defines things such as:
settings.pyINSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]This section lists the apps that are active in your project.
Another example:
DEBUG = TrueThis enables debug mode during development.
And:
ALLOWED_HOSTS = []This controls which hosts are allowed to serve the project.
settings.py mattersYou will frequently edit this file when:
It is the central configuration file of your Django project.
urls.pyThe file:
config/urls.pydefines the main URL routes of your project.
urls.py doesIt tells Django which view should handle a requested URL.
For example:
from django.contrib import admin
from django.urls import path
urlpatterns = [
path('admin/', admin.site.urls),
]This means that when the user visits /admin/, Django opens the admin interface.
As your project grows, you will connect more URLs to different apps and views.
For example:
//blog//contact//shop/This file acts like the central traffic controller of the project.
wsgi.pyThe file:
config/wsgi.pyis used for deployment in traditional Python web server setups.
WSGI stands for:
Web Server Gateway Interface
It is a standard interface between web servers and Python web applications.
wsgi.py doesIt exposes your Django application so that production servers like Gunicorn or uWSGI can serve it.
When you are just learning Django, you usually do not need to edit this file. But it becomes useful when deploying your project.
asgi.pyThe file:
config/asgi.pyis similar to wsgi.py, but it is designed for modern asynchronous features.
ASGI stands for:
Asynchronous Server Gateway Interface
ASGI supports:
For simple projects, you will not usually edit this file at the beginning. But it is part of modern Django architecture.
Let us simplify the flow.
When a user visits a page:
urls.py checks the URLThe configuration in settings.py supports all of this in the background.
So each file has a role:
manage.py → command-line managementsettings.py → project configurationurls.py → URL routingwsgi.py → deployment interfaceasgi.py → async deployment interface__init__.py → package initializationOnce you create an app using:
python manage.py startapp blogDjango adds another folder:
blog/
├── __init__.py
├── admin.py
├── apps.py
├── migrations/
├── models.py
├── tests.py
├── views.pyThis is where you will place app-specific logic.
This is a key concept in Django.
For example, in one project, you may have these apps:
blogusersshopdashboardThis modular structure is one of Django’s strengths.
Many beginners confuse the Django project with a Django app.
The project is the complete configuration and global container of your website.
An app is a specific component with a clear responsibility.
For an e-commerce website:
This separation helps keep code organized and reusable.
As your project grows, the structure often looks like this:
my_django_project/
│
├── venv/
├── manage.py
├── db.sqlite3
├── requirements.txt
├── config/
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.py
│
├── blog/
│ ├── migrations/
│ ├── templates/
│ ├── static/
│ ├── admin.py
│ ├── models.py
│ ├── views.py
│ └── urls.py
│
├── templates/
├── static/
└── media/
This structure becomes easier to understand once you know the role of each part.
Django uses this organization because it promotes:
Instead of putting everything in one file, Django separates configuration, business logic, presentation, and app components into well-defined places.
This makes projects easier to maintain.
When starting with Django project structure, try to follow these habits:
Use meaningful names for the project and apps.
Examples:
configblogusersstoreFor example, avoid editing asgi.py or wsgi.py unless needed.
You do not need to master every file immediately. Start with:
manage.pysettings.pyurls.pyviews.pymodels.pyEach app should have one main responsibility.
Think of a Django project like a university.
settings.py is the administration office rulesurls.py is the campus mapmanage.py is the control panelThis analogy helps you understand that Django is built around organization and separation of roles.
In this tutorial, you learned the main structure of a Django project and the role of its most important files. You now know that manage.py is used for command-line tasks, settings.py holds the configuration, urls.py handles routing, and wsgi.py and asgi.py are used for deployment.
You also learned the important difference between a Django project and a Django app. This understanding is essential before moving on to creating views, templates, and models.
<hr>
manage.py is used to manage the project from the terminal.settings.py contains the main configuration.urls.py controls URL routing.wsgi.py and asgi.py are used for deployment.manage.py?Understanding Django project structure is a major step for every beginner. Once you know where things belong, Django becomes much easier to learn. Instead of seeing a confusing collection of files, you begin to see a clear system where each part has its purpose.