Starting a Django project: installation and project structure

This series builds one real application — a blog with posts, comments, and user accounts — across 22 parts, each covering one piece of Django properly instead of skimming the whole framework at once. By the end you'll have shipped models, an admin panel, forms, authentication, and a deployed site. Part 1 is just getting a project running and understanding what Django generated for you.

Installing Django

mkdir blogsite && cd blogsite
python3 -m venv venv
source venv/bin/activate
pip install django
django-admin --version

A virtual environment first, always — installing Django globally means every Python project on the machine shares one Django version, and upgrading for one project silently breaks another.

Creating the project

django-admin startproject blogsite .

The trailing . matters: it creates the project in the current directory instead of nesting it inside an extra blogsite/blogsite/ folder. This generates:

blogsite/
    manage.py
    blogsite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

manage.py is the command-line entry point for everything — running the server, creating apps, managing the database. The inner blogsite/ directory is the project package: settings.py holds every configuration value, urls.py is the root URL routing table, and wsgi.py/asgi.py are what a production server actually talks to (part 22 comes back to these).

Running the development server

python manage.py runserver

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

System check identified no issues (0 silenced).
You have 18 unapplied migration(s)...
Django version 5.x, using settings 'blogsite.settings'
Starting development server at http://127.0.0.1:8000/

Visit http://127.0.0.1:8000/ and Django's default landing page confirms the project runs. The "18 unapplied migrations" warning is expected at this stage — those are Django's own built-in apps (admin, auth, sessions) waiting for a database. Part 6 covers migrations properly; ignore the warning until then.

FAQ

Why is the virtual environment folder named venv here instead of .venv? Either name works identically — venv and .venv are both just conventional folder names, not something Django or Python treats specially. .venv (with the leading dot) is slightly more common today since it sorts out of the way in a plain directory listing; add whichever name you use to .gitignore.

Do I need to pin a specific Django version? For following this series, any current Django 5.x release works — the concepts here are stable across minor versions. For a real project, pinning a version in requirements.txt (covered in the virtual environments guide) avoids an unexpected major-version upgrade breaking something later.

What's actually in settings.py that I should know about this early? Mainly INSTALLED_APPS (which apps are active — covered next in part 2), DATABASES (which database and how to reach it), and DEBUG (must be False in production, since True shows detailed error pages to any visitor). Most of the rest of the file is safe to leave at its generated defaults for now.

Next: creating the blog app itself — the piece that actually holds this project's code.