Your First Django App: Projects vs. Apps

1. The Distinction: Project vs. App

This is one of the most confusing concepts for Django beginners, so let’s be precise about the definitions:

• A Project is the entire website. It contains global configuration (settings, root URL routing) and ties all the pieces together. There is exactly one project per website. In our case, mysite/ is the project.
• An App is a self-contained component that handles one specific feature of the website. A project is made up of multiple apps. For example, a blog website might have a blog app (for posts), an accounts app (for user login/registration), and a comments app.

The Django documentation describes this perfectly: “A project can contain multiple apps. An app can be in multiple projects.” Apps are designed to be portable and reusable.

2. Creating Your First App

Let’s create an app called blog that will handle our blog posts. With the virtual environment active, run:

python manage.py startapp blog

This generates a new directory called blog/ inside your project:

myproject/
├── manage.py
├── mysite/
│   └── settings.py ...
│
└── blog/                   ← Your new app
    ├── __init__.py
    ├── admin.py            ← Register models with the admin panel here
    ├── apps.py             ← App configuration class
    ├── migrations/         ← Auto-generated database migration files
    │   └── __init__.py
    ├── models.py           ← Define your database tables here
    ├── tests.py            ← Write unit tests here
    └── views.py            ← Define your view functions here

3. Registering the App in settings.py

Creating the app folder is not enough — you must tell Django it exists by adding it to INSTALLED_APPS in settings.py. If you skip this step, Django will not load your models, admin registrations, or templates.

# mysite/settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # ↓ Add your new app here
    'blog',
]

The string 'blog' matches the name of the blog/ directory. Django will now discover and load everything inside it.

4. Understanding apps.py

Inside your new app, apps.py contains a configuration class:

# blog/apps.py
from django.apps import AppConfig

class BlogConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'blog'

default_auto_field tells Django what type of field to use as the automatic primary key for every model in this app. BigAutoField is a 64-bit integer that auto-increments — it is the modern default and can handle billions of rows without overflowing. You can also register the app using its full config class path for more control:

# mysite/settings.py (alternative, more explicit)
INSTALLED_APPS = [
    ...
    'blog.apps.BlogConfig',  # Uses the BlogConfig class directly
]

Both approaches work. The shorter 'blog' string is more common in tutorials; the explicit path is better for larger projects where you need to customize app behaviour.