Project Structure
startproject and startapp generate several files for you. Knowing what each one does helps you find your way around any Django codebase, including ones written by other people.
The complete layout
After creating the campus project and the events app, and running migrate, your folder looks like this:
campus-events/
├── .venv/ virtual environment (never edit by hand)
├── db.sqlite3 the database, created by migrate
├── manage.py command-line helper for this project
├── requirements.txt list of installed packages
├── campus/ project configuration package
│ ├── __init__.py
│ ├── asgi.py
│ ├── settings.py
│ ├── urls.py
│ └── wsgi.py
└── events/ an app
├── __init__.py
├── admin.py
├── apps.py
├── migrations/
│ └── __init__.py
├── models.py
├── tests.py
└── views.py
Project-level files
manage.py
A small script that runs Django commands for this specific project. It sets the DJANGO_SETTINGS_MODULE environment variable to campus.settings and then hands over to Django. You use it constantly:
python manage.py runserver # start the development server python manage.py startapp events # create an app python manage.py makemigrations # prepare database changes python manage.py migrate # apply database changes python manage.py createsuperuser # create an admin user python manage.py shell # Python shell with Django loaded
You almost never need to edit manage.py itself.
campus/settings.py
The control panel for the whole project. Some of the settings you'll touch most:
| Setting | What it controls |
|---|---|
SECRET_KEY | A secret value used to sign cookies and tokens. Must be kept private in production. |
DEBUG | Shows detailed error pages when True. Must be False on a live site. |
ALLOWED_HOSTS | Domain names the site may be served from. |
INSTALLED_APPS | The apps that are switched on. |
MIDDLEWARE | Code that runs on every request and response (security, sessions, CSRF). |
TEMPLATES | Where Django looks for template files. |
DATABASES | Which database to use. The default is a SQLite file, db.sqlite3. |
TIME_ZONE, LANGUAGE_CODE | Local time zone and default language. |
STATIC_URL | The URL prefix for CSS, JavaScript and images. |
For a site in Kenya, Uganda or Tanzania, set the time zone to East Africa Time. Keep USE_TZ = True so Django stores times safely in UTC and converts them for display.
campus/settings.py
LANGUAGE_CODE = "en-us" TIME_ZONE = "Africa/Nairobi" USE_I18N = True USE_TZ = True
campus/urls.py
The project's main URL list, sometimes called the root URLconf. Every request starts here. The generated file contains a single route for the admin site:
from django.contrib import admin
from django.urls import path
urlpatterns = [
path("admin/", admin.site.urls),
]
You'll extend it on the URL Routing page.
campus/wsgi.py and campus/asgi.py
Entry points for production web servers. WSGI is the traditional standard used by servers such as Gunicorn; ASGI is the newer standard that also supports asynchronous features like WebSockets. Each file creates an object called application that the server calls. You'll point Gunicorn at campus.wsgi when you deploy.
__init__.py
An empty file that tells Python "this folder is a package", so you can write imports like from campus import settings.
App-level files
| File | Purpose | Covered in |
|---|---|---|
models.py | Classes that describe your database tables | Models |
views.py | Functions or classes that handle requests | Writing Views |
admin.py | Registers models with the admin dashboard | The Admin Site |
apps.py | Configuration class for the app (name, default ID field type) | This page |
migrations/ | Generated files that record database changes | Migrations |
tests.py | Automated tests for the app | - |
Files you add yourself
Django doesn't generate everything. As the app grows you'll add these by hand:
events/
├── urls.py the app's own URL patterns
├── forms.py form classes
├── templates/
│ └── events/ templates, namespaced by app name
│ ├── event_list.html
│ └── event_detail.html
└── static/
└── events/ CSS, JavaScript and images
└── style.css
Notice the repeated events folder inside templates/ and static/. This is called namespacing. Django searches the template folders of every installed app, so if two apps both had a file called templates/index.html, one would hide the other. Putting files in templates/events/ and referring to them as "events/event_list.html" avoids the clash.
Committing db.sqlite3, .venv/ or a real SECRET_KEY to a public GitHub repository. Add the first two to .gitignore, and read Settings & Security to learn how to keep secrets out of your code.
Key points
manage.pyruns commands;settings.pyconfigures the project;urls.pyis where every request starts.wsgi.pyandasgi.pyconnect your project to production servers.- Each app has its own
models.py,views.py,admin.pyandmigrations/. - Add
urls.py,forms.py,templates/app_name/andstatic/app_name/yourself.
Tip: use the ← and → keys to move between pages.
