Build Your First Django App

You’ve learned Python basics and maybe even heard Django’s name whispered in job postings and GitHub READMEs — but the moment you try to start, you’re buried under terms like manage.py, settings.py, and urlpatterns before you’ve written a single line of your own logic. The pain is real: Django’s project structure feels upside-down, and most tutorials jump straight into advanced topics like forms and authentication, leaving you stranded if something goes wrong. This lesson cuts through the noise by walking you through the exact steps to build your first Django app — from a blank folder to a working web page you can show off in your browser — and gives you the mental model to keep building without fear.

The problem this lesson solves

Every Django beginner hits the same wall: the framework generates a lot of files, and nothing looks like the simple hello.py scripts you’re used to. The classic mistake is to treat those files as sacred and modify them blindly, which leads to broken apps and frustration. This lesson solves that by showing you what each piece actually does, so you can confidently build your first Django app without guessing.

When you finish, you’ll be able to explain the core ideas behind Django’s project–app split, create and register an app, write a view, map a URL, and serve an HTML response. That’s the foundation every later lesson — models, templates, forms, authentication — builds on. Without this step, nothing else in the track will make sense.

Core concept / mental model

Think of a Django project as the orchestra and an app as a musician. The project holds the global settings, the root URL configuration, and the list of installed apps. The app contains the actual features — views, models, templates — that play the music. You can have many musicians (apps) in one orchestra (project), like blog, polls, or shop. The project tells Django which apps are active and how to route incoming HTTP requests to the right view inside those apps.

Here’s the simple mental model for a request lifecycle:

1. A user hits a URL like http://localhost:8000/hello/.
2. Django looks at the project’s root urls.py file and finds a matching pattern.
3. That pattern points to a view (a Python function) inside one of your apps.
4. The view runs its logic and returns an HttpResponse (or a rendered template).
5. Django sends that response back to the browser.

Pro tip: Keep this request flow in your head — it’s the heartbeat of every Django feature you’ll build. Everything else is elaboration.

How it works step by step

The process from zero to a running Django app follows a repeatable sequence. Once you internalize it, you’ll be able to start new projects in minutes.

1. Create a virtual environment

Isolating your dependencies is best practice. Create a folder, set up a virtual env, and activate it.

2. Install Django

Use pip to install Django in that environment. You’ll run pip install django — one line, but it changes everything.

3. Create the project

The django-admin startproject command generates the project skeleton — manage.py, settings.py, urls.py, wsgi.py, and asgi.py. This is your orchestra.

4. Create the app

Inside the project folder, run python manage.py startapp followed by a name like core or polls. This creates the app folder with views.py, models.py, and more.

5. Register the app in settings.py

Add your app’s name to the INSTALLED_APPS list. Without this step, Django won’t know your app exists — a classic gotcha.

6. Write a view

Edit views.py in your app to define a function that returns an HttpResponse with a simple message.

7. Map a URL

Create or edit a urls.py file inside your app, then include it from the project’s root urls.py. Now your view is reachable.

8. Run the development server

Use the built-in server to see your app live. You’ll see the development server logs and can interact with your app in the browser.

Pro tip: The development server auto-reloads when you save .py files — but only if your code is syntactically correct. If you see a syntax error message, fix the typo before it can reload.

Hands-on walkthrough

Let’s actually build your first Django app now. Open a terminal and follow along. I’m assuming Python 3.10 or newer is already installed.

Step A: Set up the environment

mkdir myfirstsite
cd myfirstsite
python -m venv venv
# Activate:
# Windows: venv\Scripts\activate
# macOS/Linux: source venv/bin/activate

Step B: Install Django

pip install django

Now create the project and the app:

django-admin startproject myproject .
python manage.py startapp core

The . after startproject creates manage.py in the current directory instead of a nested folder. The app folder core now contains views.py, models.py, admin.py, and more.

Step C: Register the app

Open myproject/settings.py and find INSTALLED_APPS. Add 'core' at the end of the list, like this:

# myproject/settings.py
INSTALLED_APPS = [
    # Django built-in apps...
    'core',
]

Step D: Write the view

Open core/views.py and replace its content with:

# core/views.py
from django.http import HttpResponse

def home(request):
    return HttpResponse("Hello, Django! This is my first app.")

Step E: Create the app-specific URL config

Create a new file core/urls.py and add:

# core/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
]

Step F: Include it in the project’s urls.py

Open myproject/urls.py and modify it to:

# myproject/urls.py
from django.contrib import admin
from django.urls import path, include

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

Step G: Run the server

python manage.py runserver

Open http://127.0.0.1:8000/ in your browser. You should see “Hello, Django! This is my first app.”

Expected output: The terminal shows Starting development server at http://127.0.0.1:8000/, and your browser renders the message. That’s your first Django app working!

Compare options / when to choose what

You have several ways to structure your Django setup, and knowing when to choose each helps you build your first Django app the right way.

For your first Django app, stick with a single core app. As you progress, split features into dedicated apps only when the code starts to feel cluttered.

Pro tip: Django apps aren’t microservices. They’re just Python packages designed to be plug-and-play. One app per feature is the sweet spot.

Troubleshooting & edge cases

You’ll run into common issues even in these first steps. Here’s how to fix them fast.

“No module named ‘core’”

This means the app isn’t in INSTALLED_APPS, or the app folder isn’t in the Python path. Double-check your settings.py and ensure you ran startapp from the same directory as manage.py.

“Page not found (404)” at the root URL

You probably didn’t include your app’s URL config. Confirm path('', include('core.urls')) is in the project’s urlpatterns. If your app should handle a different path like /hello/, use path('hello/', include('core.urls')) instead.

“DisallowedHost at /” error

When you run runserver and access via a domain other than localhost, Django blocks it. Add your host to ALLOWED_HOSTS in settings.py (e.g., ALLOWED_HOSTS = ['yourdomain.com', 'localhost']). For local development, leave it as ['localhost', '127.0.0.1'].

The server starts but your changes don’t appear

If you edited a Python file and the server still shows old content, check for a syntax error in the terminal. Django won’t reload if the code is broken, but it still serves the last working version to the browser. Fix the typo, and it will reload automatically.

Port 8000 already in use

Run python manage.py runserver 8001 to use a different port, or close the other process.

Pro tip: The development server is only for local development. For production, use a WSGI server like Gunicorn with python manage.py collectstatic and proper security settings — but that’s a later lesson.

What you learned & what's next

You’ve successfully built your first Django app. Let’s recap the core ideas you now understand:

• A Django project is the configuration umbrella; an app contains the feature logic.
• The request flow: URL → urls.py → view → HttpResponse.
• You can create a project and app with django-admin and manage.py commands.
• Register apps in INSTALLED_APPS and include app URLs in the root urls.py.
• The development server is your best friend for quick iteration.

These are the load-bearing walls of Django development. With this foundation, you’re ready for the next natural step: building actual database-driven features with Django models and the ORM. In the next lesson, you’ll learn how to define data structures, create migrations, and store real information in a database — powering dynamic content beyond a simple Hello World response.

Go ahead and experiment: change the view’s text, add another URL path, or return HTML instead of plain text. The more you touch the code, the more the mental model solidifies. See you in the next lesson!