Skip to content
Kuza Ndoto Academy

Installing Django

IntermediateChapter 1 · Page 2 of 234 min readUpdated 15 Nov 2026

Before you write any Django code you need three things: Python, a virtual environment for your project and Django itself. This page walks you through the setup on Windows, macOS and Linux and ends with Django's development server running in your browser.

Step 1: Check that Python is installed

Django 5.2 supports Python 3.10 and newer, and this series uses Python 3.12+. Open a terminal (Command Prompt or PowerShell on Windows, Terminal on macOS and Linux) and check your version.

python --version
Python 3.12.7

Any version from 3.12 upwards is fine. On macOS and Linux the command may be python3 instead of python. If Python is missing, follow Installing Python & VS Code first.

Step 2: Create a project folder and a virtual environment

A virtual environment is a private folder of packages for one project. It keeps this project's Django version separate from every other project on your computer. (See pip & Virtual Environments for the full story.)

mkdir campus-events
cd campus-events
python -m venv .venv

This creates a hidden folder called .venv. Now activate it. The command depends on your system:

# Windows (Command Prompt or PowerShell)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

When it is active, your prompt starts with (.venv). Every pip install now goes into this project only.

Common mistake

Opening a new terminal and forgetting to activate the environment. If you see ModuleNotFoundError: No module named 'django', check that your prompt shows (.venv) and activate again if it doesn't.

Step 3: Install Django

Use pip to install the latest 5.2 release. The ~=5.2.0 part means "version 5.2.0 or any later 5.2.x bug-fix release", so you get security fixes without jumping to a new major version by accident.

python -m pip install "django~=5.2.0"
... Successfully installed asgiref-3.10.0 django-5.2.8 sqlparse-0.5.3 tzdata-2025.2

Your exact version numbers will differ. Django brings two helper packages with it: asgiref (support for asynchronous servers) and sqlparse (used to format SQL). On Windows, pip also installs tzdata so that Django can work with time zones.

Confirm the install:

python -m django --version
5.2.8

It's good practice to record your project's packages in a requirements.txt file so that others (and your future server) can install exactly the same versions:

python -m pip freeze > requirements.txt

Step 4: Create a project and run the development server

Django installs a command-line tool called django-admin. Use it to generate a new project called campus. The dot at the end means "put it in the current folder" instead of creating an extra nested folder.

django-admin startproject campus .

This prints nothing when it succeeds. Now start Django's built-in 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). 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. November 15, 2026 - 10:30:12 Django version 5.2.8, using settings 'campus.settings' Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C. WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead. For more information on production servers see: https://docs.djangoproject.com/en/5.2/howto/deployment/

Open http://127.0.0.1:8000/ in your browser and you'll see Django's welcome page with a rocket and the message "The install worked successfully! Congratulations!". On Windows the quit message says CTRL-BREAK, but Ctrl+C works too. Your date and version will differ.

The message about 18 unapplied migrations is normal: Django's built-in apps need database tables. You'll learn about them on the Migrations page. For now you can create them with:

python manage.py migrate
Tip

If port 8000 is already in use, run the server on another port: python manage.py runserver 8080. The development server reloads automatically whenever you save a Python file, so you rarely need to restart it.

Warning

The development server is for your own computer only. It is not built to be fast or secure enough for real visitors. When you go live you'll use a proper server such as Gunicorn, covered in Deploying Django.

VS Code with the official Python extension works well. Open the campus-events folder, then choose your .venv interpreter (Command Palette, then "Python: Select Interpreter") so that the editor understands your Django imports. Add .venv/ and db.sqlite3 to a .gitignore file if you use Git.

Key points

  • Create one virtual environment per project and activate it before working.
  • Install Django with python -m pip install "django~=5.2.0" and check it with python -m django --version.
  • django-admin startproject campus . generates a new project in the current folder.
  • python manage.py runserver starts the development server at http://127.0.0.1:8000/.
Up next · Getting StartedProjects vs. AppsHow Django organises a website.
→

Tip: use the ← and → keys to move between pages.