Skip to content
Kuza Ndoto Academy

Projects vs. Apps

IntermediateChapter 1 · Page 3 of 233 min readUpdated 15 Nov 2026

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.

Example

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.

campus-events/ (the project folder) campus/ settings.py, urls.py events/ your app accounts/ your app built-in apps admin, auth... manage.py db.sqlite3 Apps are switched on by listing them in INSTALLED_APPS in settings.py
Figure 1. One project holds the configuration; each app is a self-contained feature. Django's own admin and auth are apps too.

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.

Common mistake

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.

SitePossible apps
Campus Eventsevents (listing and managing events), accounts (sign-up and profiles)
Online shopproducts, cart, orders, payments (e.g. M-Pesa integration)
School portalstudents, 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, email or site.
  • 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.
Up next · Getting StartedProject StructureWhat every generated file does.
→

Tip: use the ← and → keys to move between pages.