Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 2

Django Project Structure Explained

Recommended resources

Hello again! In our last lesson, you successfully installed Django and created a new project skeleton. You saw the startproject command generate a collection of files and directories, and you even ran the development server.

Today, we're going to demystify that generated structure. This lesson will walk you through the purpose of each file and directory in a new Django project. Understanding this architecture is fundamental, as it's the map you'll use to navigate and build every Django application. We will also explore one of Django's core design philosophies: the distinction between a project and an app.

1. Projects vs. Apps: The Core Philosophy

Before we look at individual files, it's essential to understand the distinction Django makes between a "project" and an "app." This is a key architectural concept.

  • A Project is the entire web application. It represents a collection of configurations and apps for a particular website. The project-level files handle things like database settings, URL routing, and other global configurations.
  • An App is a self-contained module within a project that serves a specific business function. Think of a blog system, a user authentication system, or a polling app.

The goal is reusability. A well-designed app, like a user authentication system, can be dropped into different projects with minimal modification. Your Python background with modules and packages is a good parallel: you can think of a Django project as the main executable program, and the apps are the various libraries and modules it imports to perform specific tasks.

To get the official definition, please read the following section from the Django documentation.

Writing your first Django app, part 1

This section from the official Django tutorial provides a clear and concise explanation of the 'Project vs. App' concept.

In the tutorial, read the section titled 'Projects vs. apps'. It clearly outlines the difference and is a concept we will build upon throughout the course.

2. The Project Directory Structure

When you ran django-admin startproject mysite ., Django created a specific structure. Let's examine the files and directories at the project level.

Django Project File Structure
This image shows a common project structure. You can see the `manage.py` file at the top level, alongside the project configuration directory (`MyDjangoProject` in the image, or `mysite` in our case) and an app directory (`polls`).

Let's break down the purpose of each of these project-level files.

Learn Django in 20 Minutes!!

For a quick video overview, this clip from Tech With Tim clearly explains the role of each file generated by the startproject command.

Watch from 02:29 to 03:37. The video walks through __init__.py, asgi.py, wsgi.py, settings.py, urls.py, and manage.py.

For a more detailed and authoritative reference, the official documentation is the best source.

Writing your first Django app, part 1

The Django documentation provides the definitive guide to the files created by startproject. Please read this section carefully.

Locate the list of files that appears just after the 'Let’s look at what startproject created:' text. Read the descriptions for each file in the list.

Here is a summary of those files and their roles:

  • manage.py: Your project's command-line utility. It's a thin wrapper around the django-admin tool. You'll use it for almost all interactions with your project, such as running the server (runserver), creating database migrations (makemigrations), and creating new apps (startapp).

  • The inner mysite/ directory: This directory is the actual Python package for your project. Its name is what you'll use to import anything inside it (e.g., from mysite.settings import DEBUG).

    • mysite/__init__.py: An empty file that tells Python that this directory should be treated as a Python package. Your experience with Python packages means you're already familiar with this concept.

    • mysite/settings.py: This is the heart of your project's configuration. It contains settings for your database, installed applications, static files, time zone, security keys, and much more. We will spend a lot of time in this file.

    • mysite/urls.py: The "table of contents" for your website. It contains the project-level URL declarations. When a request comes to your site, Django uses this file to determine which view should handle it.

    • mysite/wsgi.py and mysite/asgi.py: These are the entry-points for WSGI- and ASGI-compatible web servers, respectively. They act as the bridge between your Django application and a production web server like Gunicorn or Uvicorn.

      • WSGI (Web Server Gateway Interface) is the long-standing Python standard for communication with synchronous web servers.
      • ASGI (Asynchronous Server Gateway Interface) is its spiritual successor, designed to handle both synchronous and asynchronous applications, which is essential for features like WebSockets.

3. The Application Directory Structure

Now that we understand the project container, let's look at the structure of an app. While the next lesson will cover creating an app, understanding its internal structure now helps clarify its role. You would create an app with the command: python manage.py startapp <app_name>.

This creates a new directory with its own set of files, each with a specific purpose.

Django Project Structure: A Comprehensive Guide

This article provides a great breakdown of the files generated within a Django app and their roles.

Read the section titled 'Application directory', focusing on the subsection 'Generated files and their roles'. This details the purpose of models.py, views.py, tests.py, and admin.py.

Here's a summary of the most important files in a new app (e.g., an app named polls):

  • polls/migrations/: This directory stores your database migration files. Migrations are Python files that represent changes to your database schema (your models).
  • polls/admin.py: This file is where you register your models to be included in Django's powerful, built-in admin interface.
  • polls/apps.py: Contains the configuration for this specific application.
  • polls/models.py: This is where you define your application's data models using Django's Object-Relational Mapper (ORM). Each class you define here typically maps to a single database table.
  • polls/tests.py: Django includes a testing framework, and this is where you write your tests for the app.
  • polls/views.py: This file contains the logic that handles HTTP requests and returns HTTP responses. When a request comes in and the project's urls.py directs it to this app, a function or class in this file will be executed.
Test your understanding!

You are building a web application for a bookstore. You need to add a feature to manage book inventory.

  1. Should this be a new Django project or a new Django app?
  2. Which file within the new component would you edit to define the data structure for a Book (e.g., its title, author, and price)?
Show answer
  1. This should be a new Django app, perhaps named inventory or books. It's a specific feature within the larger bookstore project.
  2. You would define the Book data structure in the models.py file of your new app.

4. A Recommended Structure for Scalability

While Django's default structure is good, as projects grow, developers often adopt a slightly more organized structure for better maintainability. This is especially relevant for backend development where you might manage many apps.

Django Folder Structure Diagram
This diagram illustrates a common best-practice structure. Key features to note are the top-level `templates` and `static` directories for project-wide assets, and placing all applications inside a dedicated `apps` directory.

This structure introduces a few key ideas:

  • A top-level apps directory: All your custom apps (app1, app2, etc.) live inside a dedicated apps folder. This keeps your project root clean and clearly separates your code from configuration.
  • Top-level templates and static directories: While each app can have its own templates and static files (CSS, JS), it's common practice to have project-wide directories for shared base templates and global static assets. We will explore this in detail in Module 2.

You don't need to use this structure now, but it's valuable to see how projects are organized in a professional setting.

Conclusion

You now have a mental map of a Django project. You understand the "why" behind its design and the role of each key component.

Here are the main takeaways:

  • A project is the overall configuration container for a website.
  • An app is a modular, reusable component that provides a specific feature.
  • manage.py is your command-line tool for interacting with the project.
  • settings.py is the central nervous system, holding all project configurations.
  • urls.py acts as the main router, directing web requests to the correct place.
  • Apps contain the core logic of your features in files like models.py (data) and views.py (request handling).

In our next lesson, we will zoom in on the most important file we've discussed: settings.py. You will learn how to configure essential settings like DEBUG, ALLOWED_HOSTS, and INSTALLED_APPS to get your project ready for development.