Difficulty: Beginner
Setting up a Django project properly is the foundation for successful development. Django is distributed as a Python package through PyPI and is installed using pip, Python's package manager. Before installing Django, it is critical to create a virtual environment to isolate your project's dependencies from other Python projects on your system.
A virtual environment is a self-contained directory that contains a Python installation and its own set of packages. Without virtual environments, all Python projects on your machine would share the same globally installed packages, leading to version conflicts. For example, one project might need Django 4.2 while another needs Django 5.1. Virtual environments solve this by giving each project its own isolated package space.
Python 3 ships with the venv module built-in, which is the recommended way to create virtual environments. You create a virtual environment by running 'python -m venv venv' in your project directory, which creates a venv folder containing a clean Python installation. You then activate it with 'source venv/bin/activate' on Linux/Mac or 'venv\Scripts\activate' on Windows. Once activated, any packages you install with pip will be contained within this virtual environment.
After activating your virtual environment, install Django with 'pip install django'. This downloads Django and its dependencies (primarily asgiref and sqlparse) from PyPI. It is good practice to pin your dependencies by running 'pip freeze > requirements.txt' after installation, which records the exact package versions for reproducibility.
Django provides the django-admin command-line utility for creating new projects. Run 'django-admin startproject myproject' to scaffold a new Django project. This creates a directory structure with a manage.py file and an inner project package. The manage.py file is a thin wrapper around django-admin that sets the DJANGO_SETTINGS_MODULE environment variable for your project. You will use manage.py for all subsequent management commands like running the development server, creating database migrations, and running tests.
The startproject command creates several files. The outer directory is just a container and can be renamed. Inside it, manage.py serves as the command-line interface for your project. The inner directory (which shares the project name) is the actual Python package. It contains __init__.py (which makes it a Python package), settings.py (all project configuration), urls.py (the root URL configuration), asgi.py (entry point for ASGI-compatible web servers), and wsgi.py (entry point for WSGI-compatible web servers).
The settings.py file is the heart of Django configuration. It contains settings for databases, installed apps, middleware, templates, static files, and much more. Django uses sensible defaults for most settings, so a fresh project works immediately. The most important settings you will modify early on are INSTALLED_APPS (to register new apps), DATABASES (to configure your database), and TEMPLATES (to set up template directories).
To verify everything works, run 'python manage.py runserver' to start Django's built-in development server. By default it runs on http://127.0.0.1:8000/. You should see the Django welcome page confirming your installation was successful. This development server automatically reloads when you change code, making development fast and iterative. Note that this server is for development only - in production, you should use a proper WSGI server like Gunicorn or uWSGI.
# 1. Create and activate virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
# 2. Install Django
pip install django
# 3. Create a new project
django-admin startproject myproject
# 4. Navigate into the project
cd myproject
# 5. Run the development server
python manage.py runserver
# Visit http://127.0.0.1:8000/ in your browserThis is the standard workflow for starting a new Django project. Always use a virtual environment to isolate dependencies. The development server auto-reloads on code changes.
myproject/ # Outer container directory
manage.py # CLI for project management
myproject/ # Inner Python package
__init__.py # Makes this a Python package
settings.py # All project configuration
urls.py # Root URL configuration
asgi.py # ASGI entry point
wsgi.py # WSGI entry pointThe outer directory is a container that can be renamed. The inner directory is the actual Python package containing all configuration files. manage.py is your primary tool for running commands.
# myproject/settings.py
import os
from pathlib import Path
# Build paths relative to the project directory
BASE_DIR = Path(__file__).resolve().parent.parent
# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = 'django-insecure-your-secret-key-here'
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True
ALLOWED_HOSTS = []
# Application definition
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
# Database configuration
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'db.sqlite3',
}
}
LANGUAGE_CODE = 'en-us'
TIME_ZONE = 'UTC'
STATIC_URL = 'static/'settings.py contains all project configuration. BASE_DIR provides a reliable base path. DEBUG should be True in development and False in production. INSTALLED_APPS lists all active Django applications. The default database is SQLite.
# Save current package versions
pip freeze > requirements.txt
# The file will contain something like:
# asgiref==3.8.1
# Django==5.1
# sqlparse==0.5.1
# To install from requirements.txt (e.g., on a new machine)
pip install -r requirements.txtAlways freeze your dependencies into a requirements.txt file. This ensures that anyone setting up the project installs the exact same package versions, preventing 'works on my machine' issues.
pip, Virtual Environment, django-admin, startproject, manage.py