Installing Django
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
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.
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"
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
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
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
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.
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.
Recommended editor setup
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 withpython -m django --version. django-admin startproject campus .generates a new project in the current folder.python manage.py runserverstarts the development server athttp://127.0.0.1:8000/.
Tip: use the ← and → keys to move between pages.
