Before we proceed, it’s important to understand how a typical Django project is structured.

Django’s project structure is thoughtfully designed to make your code clean and maintainable.

Whether building a simple blog or a complex web application, understanding this structure is critical for managing your project efficiently as it grows.

Below, we’ll explore the key components of a typical Django project and how they work together.

Assumptions

This post will assume that you have your development already configured for Django/Python development.

Project Directory

When you create a new Django project, it generates a root directory with the project name. This directory contains the entire Django project.

To start a Django Project, you run:

django-admin startproject <project_name>

i.e: if you start your project by running: django-admin startproject my_project

my_project/
    manage.py
    my_project/

manage.py

This is a command-line utility that lets you interact with your Django project. It runs the development server, creates database tables, and more.

Project Settings Directory

Inside the root directory, there’s another directory with the same name as your project, my_project. This contains the project-wide settings and configurations.

my_project/
    __init__.py
    settings.py
    urls.py
    asgi.py
    wsgi.py

  • init.py: A file that tells Python that all files in the directory should be considered a Python package. Without this file, we cannot import files from another directory which we will be doing a lot of in Django!

  • settings.py: Contains all the project’s settings and configurations.

  • urls.py: The URL declarations for the project are a “table of contents” of your Django-powered site.

  • asgi.py: allows for an optional Asynchronous Server Gateway Interface(ASGI) to be run

  • wsgi.py: An entry point for Web Server Gateway Interface(WSGI) compatible web servers to serve your project. It helps Django serve our eventual web pages.

Applications

Django projects are composed of one or more apps. Each app is a Python package that follows a certain convention.

To create an application inside an already initiated django project:

manage.py startapp <app_name>

for instance running manage.py startapp app1 creates:

app1/
    __init__.py
    admin.py
    apps.py
    models.py
    tests.py
    views.py
    migrations/
        __init__.py

  • admin.py: Configuration for the Django admin interface.

  • apps.py: Configuration for the app itself.

  • models.py: Contains the database models for the app.

  • tests.py: Contains tests for the app.

  • views.py: Contains the request/response logic for the app.

  • migrations/: Contains database migrations for the app.

Templates

Templates(what users see, HTML and CSS) are typically stored in a ‘templates’ directory within each app or in a project-wide templates directory.

Static Files

Static files (CSS, JavaScript, images) are usually stored in a ‘static’ directory within each app or in a project-wide static directory.

my_project/
    static/
        app1/
            css/
            js/
            images/

Media Files

User-uploaded files are stored in a ‘media’ directory at the project root level.

my_project/
    media/
        uploads/

Conclusion:

This structure helps organize your Django project efficiently, making it easier to maintain and scale as your project grows. Remember, Django is flexible; you can adjust this structure to fit your needs.

There are so many people with different opinions on how to structure their Django projects, what I’ve shared above is the structure that comes by default. Check out the resources below

Extra Resources - Videos

Django Project Made easy - pycharm

Layered Django project structure for large-scale collaboration

django explained

Extra Resources - Written

  1. https://asgi.readthedocs.io/en/latest/specs/main.html
  2. https://docs.djangoproject.com/en/5.2/intro/tutorial01/
  3. https://docs.djangoproject.com/en/5.2/ref/applications/
  4. https://learndjango.com/tutorials/django-best-practices-projects-vs-apps
  5. https://code.visualstudio.com/docs/python/tutorial-django
  6. https://www.jetbrains.com/help/pycharm/creating-django-application-in-a-project.html
  7. https://www.reddit.com/r/django/comments/1k1k28w/django_middleware_explained_a_beginnerfriendly/