Project Structure Tour

1. Introduction

In this guide we will walk through every file and folder that Django generated when you ran startproject. Understanding the structure before you start building saves a lot of confusion later.

• You should have already created your Django project. If not, see Create First Project.
• Your .venv should be active and Django 5.2 installed.

2. The full project structure

After creating your project with the dot option, your folder should look like this:

myproject/
├── .venv/
├── manage.py
├── requirements.txt
└── mysite/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    ├── asgi.py
    └── wsgi.py

We will go through each part one by one.

3. manage.py

manage.py is the command line tool you will use every day. It sits at the root of your project and gives you access to all Django management commands.

Common things you do with it:

# Start the development server
python manage.py runserver

# Create database tables from your models
python manage.py migrate

# Create a new app inside the project
python manage.py startapp appname

# Open an interactive Python shell with Django loaded
python manage.py shell

# Check the project for common problems
python manage.py check

4. mysite/settings.py

This is the most important file in your project. All configuration lives here. You will edit this file regularly as your project grows.

Key settings you will work with early on:

• SECRET_KEY — a long random string Django uses for security. Never share it or commit it to a public repository.
• DEBUG — set to True during development. Always set to False in production.
• ALLOWED_HOSTS — a list of domain names or IP addresses your site can be served from. Empty during development, required in production.
• INSTALLED_APPS — a list of all apps active in your project. Every app you create must be added here.
• DATABASES — your database connection settings. Django uses SQLite by default, which is fine for development.
• STATIC_URL — the URL prefix for static files like CSS and JavaScript.
• TIME_ZONE — set this to your local timezone so dates and times display correctly.

5. mysite/urls.py

This is the main URL configuration file for your project. It maps incoming URLs to the correct view. Think of it as a routing table — when a request comes in, Django checks this file to decide what to do with it.

By default it looks like this:

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

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

As you add apps, you will add more paths here or use include() to point to each app's own URL file. We will cover this in the URLs and Routing section.

6. asgi.py and wsgi.py

These two files are entry points for web servers when you deploy your project. You do not need to touch them during development.

• wsgi.py — used by traditional synchronous web servers like Gunicorn or uWSGI. This is the standard choice for most Django deployments.
• asgi.py — used by async-capable servers like Daphne or Uvicorn. Required if you use Django Channels or async views.

7. mysite/__init__.py

This is an empty file. Its only purpose is to tell Python that the mysite folder is a Python package so it can be imported. You will never need to edit it.

8. Where other things go

As your project grows, you will add more folders alongside manage.py. Here is a preview of what a typical Django project looks like after a few apps are added:

myproject/
├── .venv/
├── manage.py
├── requirements.txt
├── mysite/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── blog/               ← an app you create
│   ├── migrations/
│   ├── templates/
│   ├── models.py
│   ├── views.py
│   └── urls.py
├── templates/          ← project-wide templates
└── static/             ← project-wide static files

Each app lives in its own folder at the same level as mysite. Apps have their own models, views, URLs, and templates. This keeps your code organized as the project grows.

9. Next steps

You now know what every file in your project does. The next step is to start the development server and see Django running in the browser for the first time.