Projects vs. Apps
Django splits a website into one project and one or more apps. Understanding the difference early saves you from messy code later and makes it easy to reuse features between sites.
What is a project?
A project is the whole website. It holds the site-wide configuration: which database to use, which apps are switched on, security settings, the top-level URL list and so on. You create it once with django-admin startproject. In our running example the project is called campus.
What is an app?
An app is a Python package that does one job inside the project, for example "events", "accounts" or "payments". Each app has its own models, views, templates and URLs. A project can contain many apps, and a well-written app can be copied into a different project and work there too.
Think of a university. The project is the whole university: one name, one set of rules, one campus address. The apps are its departments: Admissions, Library, Finance. Each department runs its own affairs, but they all follow university-wide rules and share the same buildings.
Creating an app
With your virtual environment active, run startapp from the folder that contains manage.py:
python manage.py startapp events
Django creates an events folder with a standard set of files:
campus-events/
├── manage.py
├── campus/ <- the project (configuration)
│ ├── settings.py
│ ├── urls.py
│ └── ...
└── events/ <- the new app
├── __init__.py
├── admin.py
├── apps.py
├── migrations/
│ └── __init__.py
├── models.py
├── tests.py
└── views.py
You'll learn what each file does on the Project Structure page.
Registering the app
Creating the folder is not enough. Django only knows about apps listed in INSTALLED_APPS in your settings file. Add yours at the end of the list:
campus/settings.py
INSTALLED_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
"events",
]
You can also write "events.apps.EventsConfig", which points to the configuration class in events/apps.py. Both work; the short form is common in modern projects.
Forgetting to add a new app to INSTALLED_APPS. The symptoms are confusing: makemigrations says "No changes detected", templates in the app aren't found and models don't appear in the admin. Whenever something in a new app is "invisible", check this list first.
Notice that the six apps already in the list are Django's own apps. The admin site, user accounts and sessions are all apps, built exactly the way you'll build yours. That's the clearest sign that apps are Django's main building block.
How to split a site into apps
A useful rule: you should be able to describe what an app does in one short sentence without using the word "and". If you need "and", it may be two apps.
| Site | Possible apps |
|---|---|
| Campus Events | events (listing and managing events), accounts (sign-up and profiles) |
| Online shop | products, cart, orders, payments (e.g. M-Pesa integration) |
| School portal | students, timetable, results, fees |
Don't over-think it at the start. Beginners often do best with one or two apps. You can split an app later when it grows too large.
Naming rules
- App names must be valid Python package names: lowercase letters, numbers and underscores, not starting with a number.
- Use plural nouns for apps that manage many things:
events,posts,orders. - Avoid names that clash with Python or Django modules, such as
django,test,emailorsite. - Don't give the app the same name as the project.
Key points
- A project is the whole site and its configuration; an app is one feature area.
- Create apps with
python manage.py startapp name. - Always add new apps to
INSTALLED_APPS. - Keep each app focused on one job so it stays easy to understand and reuse.
Tip: use the ← and → keys to move between pages.
