October 19, 2026

Django Project Structure and Important Files: Complete Beginner's Guide

Introduction to Django Project Structure

When you create your first Django project, Django automatically generates several files and folders. Beginners often see these files but do not understand which file controls the website's URL, database, settings, or page design.

Understanding the Django project structure is an essential step toward becoming a Django developer.

In the previous tutorial, you learned how to install Django, create a project, run migrations, and start the development server. In this tutorial, you will learn what happens inside that project.

You will understand the purpose of manage.py, settings.py, urls.py, views.py, models.py, admin.py, and other important files.

What Is a Django Project?

A Django project is the complete configuration and collection of applications required to run a website or web application.

For example, a student management website might contain features such as:

• Student registration

• Course management

• Attendance management

• User login

• Reports and dashboards

Django allows developers to organize these features into separate applications while keeping the website's overall configuration in one project.

Step 1: Create a Django Project

If you have already completed Module 2, you can use your existing project. Otherwise, create a new one.

First, activate your virtual environment and install Django if necessary.

Then run:

django-admin startproject myproject

Move into the project directory:

cd myproject

Run the development server:

python manage.py runserver

Open the local URL displayed in your terminal, usually:

http://127.0.0.1:8000/

Your Django project should now be running locally.

Step 2: Understand the Django Project Folder Structure

A newly created Django project generally has the following structure:

myproject/
│
├── manage.py
│
└── myproject/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    ├── asgi.py
    └── wsgi.py

The outer myproject directory contains the project files and manage.py.

The inner myproject directory is the Python package containing the project's configuration files.

Important: The folder names can be different if you choose a different project name.

Step 3: What Is manage.py?

The manage.py file is a command-line utility used to perform Django project management tasks.

It allows developers to run commands without manually configuring Django each time.

Common commands include:

python manage.py runserver
python manage.py startapp students
python manage.py migrate
python manage.py makemigrations
python manage.py createsuperuser

What Do These Commands Do?

runserver: Starts the development server.

startapp: Creates a new Django application.

migrate: Applies database migrations.

makemigrations: Creates migration files based on model changes.

createsuperuser: Creates a privileged user account for the Django admin interface.

For example, when you execute:

python manage.py runserver

Django starts the development server so you can test your website in a browser.

Step 4: What Is settings.py?

The settings.py file contains the main configuration of a Django project.

It controls settings such as installed applications, database connections, middleware, templates, static files, security, and time zone.

Some important settings are explained below.

1. INSTALLED_APPS

This setting specifies which Django applications are enabled in the project.

Example:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'students',
]

The students entry is appropriate after you create a Django app named students.

2. DATABASES

This setting defines the database configuration.

A new Django project commonly uses SQLite:

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

This configuration stores database information in a local SQLite database file.

Django can also be configured to use other supported databases, such as PostgreSQL or MySQL, when the appropriate drivers and settings are provided.

3. DEBUG

The DEBUG setting controls development debugging behavior.

DEBUG = True

During local development, debugging can help identify errors.

Security note: For a production website, configure DEBUG = False and set appropriate allowed hosts and other security settings.

4. TIME_ZONE

This setting determines the project's default time zone.

Example:

TIME_ZONE = 'Asia/Kolkata'

This is a common choice for an application operating on Indian Standard Time.

5. STATIC_URL

Static files include CSS, JavaScript, and images used by the website.

Example:

STATIC_URL = 'static/'

Django uses static-file configuration to identify and manage these assets.

Step 5: What Is urls.py?

The urls.py file defines URL patterns for your Django project.

It connects a requested URL to the view responsible for handling that request.

For example, a student management website may have these URLs:

• / — Home page

• /students/ — Student list

• /admin/ — Admin interface

A basic project URL configuration might look like this:

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

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

Here, the admin/ URL is connected to Django's built-in admin interface.

How Does URL Routing Work?

Suppose a visitor opens:

http://127.0.0.1:8000/students/

Django checks the configured URL patterns to find a matching route. If the route exists, Django calls the associated view.

If no matching route exists, Django normally returns a 404 Not Found response.

You will learn more about URL routing in a dedicated upcoming module.

Step 6: What Are asgi.py and wsgi.py?

Django projects commonly include asgi.py and wsgi.py.

Both provide entry points that compatible application servers can use to run a Django application.

WSGI

WSGI stands for Web Server Gateway Interface.

It is a standard interface commonly used to serve synchronous Python web applications.

ASGI

ASGI stands for Asynchronous Server Gateway Interface.

It supports asynchronous application handling and enables compatible deployment setups for applications that need asynchronous capabilities.

Main Difference

WSGI is the traditional synchronous application interface, while ASGI supports both synchronous and asynchronous application patterns.

You do not need to modify these files for ordinary beginner exercises. They become more important when configuring deployment.

Step 7: What Is a Django App?

A Django project can contain multiple apps. Each app is usually responsible for a particular part of the website.

For example:

• students — Student records

• courses — Course management

• attendance — Attendance records

• accounts — User-related functionality

This modular approach helps keep a larger application organized.

Create a Students App

Run:

python manage.py startapp students

Django creates a folder with a structure similar to this:

students/
├── migrations/
│   └── __init__.py
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── tests.py
└── views.py

Add the application to INSTALLED_APPS in your project's settings.py:

INSTALLED_APPS = [
    # Existing Django applications
    'students',
]

When updating an existing INSTALLED_APPS list, keep its existing entries. Do not replace the complete list with only students.

Step 8: What Is models.py?

The models.py file defines the data models for your application.

A model typically represents a database entity, such as a student, course, employee, or product.

For example:

from django.db import models

class Student(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField(unique=True)
    course = models.CharField(max_length=100)

    def __str__(self):
        return self.name

Explanation

name: Stores the student's name.

email: Stores an email address and requires it to be unique.

course: Stores the course name.

str(): Returns a readable representation of the student object.

Django uses the model definition to create and manage the corresponding database structure through migrations.

After creating or changing a model, run:

python manage.py makemigrations
python manage.py migrate

The first command generates migration files for detected model changes. The second applies the migrations to the database.

Step 9: What Is views.py?

The views.py file contains view functions or class-based views that handle requests and return responses.

A view may retrieve information from the database, process application logic, or render an HTML template.

Example:

from django.http import HttpResponse

def home(request):
    return HttpResponse("Welcome to Django!")

This view returns a simple text response.

To display it at the website's home URL, connect it through urls.py.

For example, create or update the project's urls.py:

from django.contrib import admin
from django.urls import path
from students import views

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', views.home, name='home'),
]

Now, when a visitor opens the root URL, Django calls the home view.

Note: This example assumes the students app has been created and added to INSTALLED_APPS.

Step 10: What Is admin.py?

The admin.py file allows you to register models with Django's built-in administration interface.

Once a model is registered, authorized administrators can manage its records through the admin site.

Example:

from django.contrib import admin
from .models import Student

admin.site.register(Student)

How to Access Django Admin

First, apply migrations:

python manage.py migrate

Create an administrator account:

python manage.py createsuperuser

Follow the prompts to create the account.

Start the development server:

python manage.py runserver

Open:

http://127.0.0.1:8000/admin/

Log in using the superuser credentials you created.

After registering the Student model, you should be able to manage student records through the admin interface.

Step 11: What Are apps.py, tests.py, and migrations?

apps.py

The apps.py file contains the configuration class for a Django app.

Django uses this configuration to identify and configure the application.

tests.py

The tests.py file is commonly used to write automated tests.

Tests help verify that views, models, and application behavior work as expected.

Example:

from django.test import TestCase

class BasicTest(TestCase):
    def test_basic_assertion(self):
        self.assertEqual(2 + 2, 4)

Run tests with:

python manage.py test

migrations/

The migrations directory stores migration files that describe changes to database structure.

For example, when you add a new field to a model, Django can generate a migration describing that change.

Migration files help keep the database structure synchronized with your model definitions.

Step 12: What Is the Template Folder?

Templates are generally HTML files used to display website pages.

For example, you might create:

students/
└── templates/
    └── students/
        └── home.html

The home.html file could contain:

<!DOCTYPE html>
<html>
<head>
    <title>My Django Website</title>
</head>
<body>
    <h1>Welcome to Django</h1>
    <p>This is my first Django template.</p>
</body>
</html>

To render this template from the students app, update the view:

from django.shortcuts import render

def home(request):
    return render(request, 'students/home.html')

Django will search the configured template locations for the file.

By default, Django's app template discovery can find templates stored in a templates directory inside an installed app when APP_DIRS is enabled in the template configuration.

Step 13: Understand the Complete Request Flow

Let's connect the important files together.

Suppose a visitor opens the student list page.

The process generally works as follows:

1. The browser sends a request to Django.

2. Django checks the project's urls.py.

3. The matching URL pattern calls the relevant view in views.py.

4. The view may retrieve records using models from models.py.

5. The view may render an HTML template.

6. Django returns the response to the browser.

The admin interface and other responses can follow different internal paths, but the same general request-response concepts help you understand Django applications.

Common Beginner Mistakes

Mistake 1: Creating an App but Not Registering It

If you create an app but forget to add it to INSTALLED_APPS, Django may not discover its models and other application components as expected.

Solution: Add the app to the installed applications list.

Mistake 2: Editing the Wrong urls.py

A new project may have both a project-level urls.py and app-level URL configuration files that you create yourself.

Solution: Identify which URL configuration is being used and include app-level URL patterns where necessary.

Mistake 3: Forgetting Migrations

Creating a model does not automatically create its database table.

Solution: Run makemigrations and migrate as appropriate.

Mistake 4: Registering the Same Model Twice

Registering the same model multiple times in the admin site can raise an AlreadyRegistered error.

Solution: Check existing registrations before adding another registration.

Mistake 5: Replacing Existing Settings

Overwriting the complete INSTALLED_APPS or DATABASES configuration can break existing functionality.

Solution: Update the required section carefully and preserve unrelated project settings.

Frequently Asked Questions (FAQs)

Q1. What is a Django project?

Answer: A Django project contains the overall configuration and applications required to run a website.

Q2. What is manage.py used for?

Answer: It runs Django management commands, such as starting the server, creating apps, and applying migrations.

Q3. What is the purpose of settings.py?

Answer: It stores project configuration, including installed apps, database settings, middleware, and templates.

Q4. What does urls.py do?

Answer: It maps URL patterns to views or other URL configurations.

Q5. What is the difference between a project and an app?

Answer: A project contains the website's overall configuration, while an app handles a specific area of functionality.

Q6. What is models.py?

Answer: It defines the application's data models and their database-related behavior.

Q7. What is views.py?

Answer: It contains the logic that processes requests and returns responses.

Q8. What is admin.py?

Answer: It is used to configure model registration and administration features in Django's admin interface.

Q9. What are migrations?

Answer: Migrations describe changes to the database schema and allow Django to apply those changes.

Q10. What is the purpose of templates?

Answer: Templates define the HTML presentation of pages and can display dynamic data.

Q11. What are WSGI and ASGI?

Answer: They are application interface standards used by compatible servers to run Python web applications.

Q12. Can one Django project have multiple apps?

Answer: Yes. A Django project can contain multiple apps, each responsible for different features.

Important Interview Questions and Answers

Q1. Explain the structure of a Django project.

Answer: A typical Django project includes manage.py and a project package containing settings.py, urls.py, asgi.py, wsgi.py, and __init__.py.

Q2. What is the difference between settings.py and urls.py?

Answer: settings.py configures the project, while urls.py defines URL patterns.

Q3. What is the difference between a model and a view?

Answer: A model defines data and database-related behavior, while a view handles requests and prepares responses.

Q4. Why do we use INSTALLED_APPS?

Answer: It identifies the Django applications enabled in a project.

Q5. What is the purpose of makemigrations?

Answer: It generates migration files based on detected model changes.

Q6. What happens when you run migrate?

Answer: Django applies pending migrations to the configured database.

Q7. How do you register a model in Django Admin?

Answer: Import the model into admin.py and register it using admin.site.register() or an appropriate ModelAdmin configuration.

Q8. What is the purpose of init.py?

Answer: It marks a directory as a regular Python package in the traditional package structure and can also contain package initialization code.

Q9. How can a view display an HTML template?

Answer: It can use Django's render() shortcut to render a template and return an HTTP response.

Q10. Why is project modularity important?

Answer: It separates functionality into manageable components, improving organization, reuse, testing, and maintenance.

Practical Exercise

Create a small Django application and complete these tasks:

1. Create an app named students.

2. Add the app to INSTALLED_APPS.

3. Create a Student model with name, email, and course fields.

4. Generate and apply migrations.

5. Register the Student model in admin.py.

6. Create a superuser and log in to Django Admin.

7. Create a home view in views.py.

8. Connect the home view through urls.py.

9. Create a template named home.html.

10. Render the template in your browser.

This exercise helps you understand how Django project files work together.

Conclusion

In this tutorial, you learned about Django's project structure and the responsibilities of its important files.

You now understand how manage.py, settings.py, urls.py, models.py, views.py, admin.py, templates, and migrations contribute to a Django application.

Understanding these files will make it easier to build, debug, and maintain real-world Django projects.

In the next tutorial, you will learn about Django URL Routing and Views, including how to create URL patterns, connect views, and return responses to users.