Install Django and Create a Project

You've learned Python, maybe built a few scripts, and now you're ready to put it online — but the blank page of "web development" is intimidating. Where do you start? Install Django and create your first project is the single biggest leap you'll make in your web dev journey, and it's surprisingly simple once you see the steps. In this lesson, you'll set up Django on your machine, generate a fully functional project skeleton, and run a live development server — all in under 15 minutes. No magic, no jargon, just a clear, repeatable path that turns your Python skills into a real web application.

The problem this lesson solves

Every web developer faces the same wall: you know what you want to build, but you don't know where to begin. You could hand-code everything — routing, database connections, URL handling — but that's thousands of hours of reinventing the wheel. Django solves that by giving you a batteries-included framework, but even powerful tools can feel overwhelming at first. The real pain is the setup paralysis: you install packages, run commands, and you have no idea if you're doing it right. This lesson eliminates that uncertainty. By the end, you'll have a working Django project on your machine, and you'll understand exactly what each file does. That foundation makes every later lesson — models, views, templates — click into place.

Core concept / mental model

Think of Django as a pre-built house. When you django-admin startproject, you're not laying bricks; you're getting a fully plumbed, wired structure. Your job is to move in furniture (your code) and customize the rooms (your views and templates). The startproject command generates a project — the configuration and management layer for your entire website. Inside it, you'll find a manage.py file (your remote control) and a package (folder) with settings and URL configurations. Separately, you'll create apps — like rooms in the house — using startapp. An app is a module that handles a specific feature (e.g., a blog, a user system). Don't confuse them: a project is the whole site; an app is a component within it. This mental model — project vs. app — is the first concept you must internalize.

How it works step by step

Here's the logical flow from zero to a running server:

1. Check your Python version — Django requires Python 3.10 or newer (as of Django 5.0). Your system may have Python 3.8, so always verify.
2. Create and activate a virtual environment — This isolates your project's dependencies. You'll use python -m venv venv, then activate it (on Windows: venv\Scripts\activate, on macOS/Linux: source venv/bin/activate).
3. Install Django — The command python -m pip install django pulls the latest stable version from PyPI.
4. Generate your project — Run django-admin startproject myproject . (the trailing dot is crucial — it tells Django to use the current directory, not create a new one). This creates manage.py, a myproject package, and the default db.sqlite3 database (empty at first).
5. Run the development server — python manage.py runserver starts a lightweight server at http://127.0.0.1:8000. Open it in your browser, and you'll see Django's smiley page confirming success.

The cause-and-effect chain is: you create an isolated environment → install Django → generate a project skeleton → run the server. Each step builds on the previous one. If you miss any, you'll hit errors — but we'll cover those in troubleshooting.

Hands-on walkthrough

Let's get your hands dirty. Open your terminal and follow along — this is the same sequence you'll repeat for every real project.

Step 1: Verify Python & create a virtual environment

# Check Python version (should be 3.10+)
python --version

# Create a new directory for your project and enter it
mkdir myfirstdjango
cd myfirstdjango

# Create a virtual environment
python -m venv venv

# Activate it (Linux/macOS)
source venv/bin/activate
# On Windows: .\venv\Scripts\activate

# Your prompt should now show (venv) at the start

Step 2: Install Django

pip install django

# Verify the installation
python -m django --version
# Output: e.g., 5.0.6

Pro tip: Use python -m pip instead of just pip to avoid ambiguity when multiple Python versions are installed.

Step 3: Create your project

# The dot is important — it uses the current folder as the project root
django-admin startproject myproject .

# See what was created
ls -l
# You'll see: manage.py, myproject/ (a folder), and possibly db.sqlite3

Step 4: Run the development server

python manage.py runserver

You'll see output like this:

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

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.

Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Now open your browser to http://127.0.0.1:8000/ — you'll see the Django rocket page. Congratulations! You've just installed Django and created your first project. The migration warning is normal — ignore it for now; that's for later lessons.

Compare options / when to choose what

While this tutorial uses the latest Django (5.0+), you might encounter other paths. Here's a quick comparison:

For this track, stick with the latest stable. You'll also see two ways to start a project: with or without the trailing dot. The dot is the best practice — it avoids nesting a project folder inside another and keeps your layout clean.

Troubleshooting & edge cases

Even the smoothest setup can hit a snag. Here are the most common errors and how to fix them:

• ModuleNotFoundError: No module named 'django' — Usually means your virtual environment isn't activated, or you installed into a different environment. Check your terminal prompt for (venv). If it's missing, run source venv/bin/activate again.
• django-admin: command not found — On Windows, the script may not be in your PATH. Use python -m django startproject instead, which is more reliable.
• Error: 'python' is not recognized — Python isn't in your PATH. Install Python correctly and check the Add Python to PATH checkbox during setup.
• Port 8000 already in use — If another server runs, start a different one: python manage.py runserver 8080 (or any other free port).
• UnicodeDecodeError or encoding issues — On Windows, set the environment variable PYTHONUTF8=1 to force UTF-8 mode, or use Git Bash instead of Command Prompt.
• Wrong folder structure — If you forget the dot in startproject, you'll get a nested myproject/myproject. No panic: just delete the inner folder and re-run with the dot. Or, cd into the outer folder and treat that as your project root.

Pro tip: If you're on Windows and seeing odd path errors, consider using Git Bash or Windows Subsystem for Linux (WSL) for a Unix-like experience.

What you learned & what's next

You've just achieved the first milestone in this Django track: you can install Django and create your first project from scratch. Let's recap the key takeaways:

• A Django project is the umbrella configuration; an app is a module inside it.
• A virtual environment keeps your dependencies isolated and project-specific.
• The startproject command generates manage.py and a settings package — the skeleton of your site.
• The development server is a lightweight, auto-reloading tool for local testing — not for production.
• Migration warnings are normal; you'll apply them in the next lesson when you learn about the database.

Next in this track: In the following lesson, we'll dissect the project structure, explore settings.py, and run your first migration to set up the built-in admin database. You'll finally see how Django's magic stays organized. For now, open your project folder in a code editor and explore the files — you've earned it!

Challenge: Create a second project in another directory using a different name (e.g., practiceproj). Run it, verify it works, and then delete the folder. Repetition is what moves this from memory to muscle.