Install Django and Start Your First Project

In the previous post we covered what Django is and why it’s still the most productive way to ship a full web product in Python. This guide is hands-on: by the end you’ll have a running Django dev server, your first app, and a clear picture of where every file lives.

If you don’t yet have Python installed, follow Install Python and Run Your First Program first.

Step 1: Create a virtual environment

Never install Django globally. Always use a virtual environment — an isolated Python installation that belongs to your project. This keeps dependencies pinned per project and avoids the dreaded “it works on my machine.”

Create a project folder and a venv inside it:

# Create and enter the project folder
mkdir mysite-project
cd mysite-project

# Create the venv (folder name is .venv by convention)
python -m venv .venv

On macOS and Linux, use python3 if python points to an old version.

Activate it:

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (cmd.exe)
.venv\Scripts\activate.bat

You’ll see (.venv) at the start of your prompt. That’s how you know the venv is active. To leave it later, run deactivate.

Step 2: Install Django

With the venv active:

pip install django

Pip fetches Django and its dependencies (only one — asgiref and sqlparse, actually two, plus tzdata on Windows) and installs them inside .venv. Verify:

python -m django --version

You should see something like 5.1.4. The exact number doesn’t matter for this tutorial — anything 4.x or 5.x will work.

Step 3: Create the project

Django distinguishes between projects and apps.

• A project is the deployable unit — your website. There’s exactly one.
• An app is a reusable feature module — a blog, a billing system, a contact form. There are many.

Create the project:

django-admin startproject mysite .

The trailing . is important. Without it, Django creates a nested mysite/mysite/ structure that confuses everyone. With it, you get a flat layout.

After running this, your folder looks like:

mysite-project/
├── .venv/
├── manage.py
└── mysite/
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

A quick tour of each file:

• manage.py — A thin wrapper around django-admin that knows about your project’s settings. You’ll run almost every command through it.
• mysite/settings.py — The project’s configuration: database, installed apps, middleware, templates, static files, secret key.
• mysite/urls.py — The root URL configuration. Every incoming URL hits this file first.
• mysite/asgi.py and wsgi.py — Entry points for production servers (Gunicorn, Uvicorn, etc.). You won’t touch these in development.
• mysite/__init__.py — Empty file that marks the folder as a Python package.

Step 4: Run the development server

The moment of truth:

python manage.py runserver

You’ll see:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). [...]
Run 'python manage.py migrate' to apply them.

Django version 5.1.4, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Open http://127.0.0.1:8000/ in your browser. You’ll see Django’s pastel-coloured welcome rocket. That’s a working web server with routing, middleware, sessions, and error handling — and you haven’t written a single line of code.

The dev server auto-reloads every time you save a Python file. Leave it running in one terminal while you work in another.

Step 5: Apply initial migrations

Django ships with several built-in apps that need database tables (users, sessions, admin, etc.). Apply their migrations:

# In a new terminal, with the venv active
python manage.py migrate

This creates a db.sqlite3 file in your project root. SQLite is the default in development — zero configuration, no separate server. You can swap it for PostgreSQL or MySQL later by editing DATABASES in settings.py.

Step 6: Create your first app

Apps are how Django organises features. Create one for a blog:

python manage.py startapp blog

Your tree now includes:

blog/
├── __init__.py
├── admin.py
├── apps.py
├── migrations/
│   └── __init__.py
├── models.py
├── tests.py
└── views.py

Each file has a job:

• models.py — Database models for this app. See Django Models and the ORM.
• views.py — View functions that handle requests. See Django Views, URLs, and Templates.
• admin.py — Registers models with the admin site. See The Django Admin.
• apps.py — The app’s configuration class. Usually left alone.
• migrations/ — Auto-generated schema changes. You’ll see files appear here as you add models.
• tests.py — Tests for this app.

Step 7: Register the app

Creating the folder isn’t enough — you have to tell the project the app exists. Open mysite/settings.py and find INSTALLED_APPS:

# mysite/settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",  # Add this line
]

Those django.contrib.* entries are the standard “apps” that ship with Django — the admin, auth, sessions, and so on. Each is a regular app, written by the Django team. Your blog is now equal to them in the system’s eyes.

Step 8: A minimal view to prove it works

Open blog/views.py:

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

def home(request):
    # Return a plain text response so we can see the wiring works
    return HttpResponse("Hello from the blog app!")

Create blog/urls.py (it doesn’t exist yet):

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

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

Include those URLs from the project’s root urls.py:

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

urlpatterns = [
    path("admin/", admin.site.urls),
    path("blog/", include("blog.urls")),
]

Save everything. The dev server will reload on its own. Visit http://127.0.0.1:8000/blog/ and you’ll see your text.

Step 9: Freeze your dependencies

Before you commit to git, snapshot what’s installed:

pip freeze > requirements.txt

That file is how anyone else (or future-you on a new laptop) recreates the environment:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Add .venv/, db.sqlite3, and __pycache__/ to a .gitignore file. They don’t belong in version control.

Common installation problems

command not found: django-admin The venv isn’t active, or Django isn’t installed in it. Run source .venv/bin/activate (or the Windows equivalent), then pip install django again.

That port is already in use. Another process is on 8000. Run the server on a different port: python manage.py runserver 8001.

Database errors on first request You probably skipped python manage.py migrate. Run it and refresh.

Changes don’t appear in the browser Make sure you saved the file. The dev server only reloads after a save. If a Python syntax error is in your file, the reload will fail — look at the terminal where runserver is running for the traceback.

Recap

You now have:

• A virtual environment with Django installed
• A scaffolded project (mysite) with settings.py, urls.py, and manage.py
• A running dev server on port 8000
• Your first app (blog) registered in INSTALLED_APPS
• A working view wired up through the URL router
• A requirements.txt you can share with anyone

This is the foundation. Every Django tutorial, book, or production codebase you’ll ever read builds on these exact pieces.

Next steps

The natural next step is to give your app some data. In Django Models and the ORM we define our first model, run makemigrations and migrate, and query the database with the ORM — no SQL required.

Related: What Is Django?, The Django Admin.

Questions or feedback? Email codeloomdevv@gmail.com.