Skip to main content

Getting Started

Django is a high-level Python web framework that encourages rapid development and clean, pragmatic design. It handles much of the hassle of web development, so you can focus on writing your app without needing to reinvent the wheel.

Prerequisites​

  • Python: Version 3.12 or greater is required.
  • Operating System: Linux, macOS, or Windows.
  • Database: Django includes a default SQLite configuration, but supports PostgreSQL, MySQL, MariaDB, and Oracle.

Installation​

It is recommended to install Django inside a virtual environment to keep your global Python installation clean.

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

# Install Django from the current directory
python -m pip install .

For production or general use, you would typically install it via pip:

python -m pip install Django

Quick Start​

Follow these steps to create a basic "Hello World" application.

1. Create a Project​

A Django project is a collection of settings and applications for a website.

django-admin startproject mysite
cd mysite

This creates a mysite/ directory containing manage.py and a mysite/ sub-package for configuration.

2. Create an App​

An app is a web application that does something (e.g., a blog or a poll).

python manage.py startapp polls

3. Write Your First View​

Open polls/views.py and add a simple view function:

from django.http import HttpResponse

def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

4. Configure URLs​

Create a file named polls/urls.py to map the view to a URL:

from django.urls import path
from . import views

urlpatterns = [
    path("", views.index, name="index"),
]

Now, include the polls URLs in the main project configuration. Edit mysite/urls.py:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("polls/", include("polls.urls")),
    path("admin/", admin.site.urls),
]

5. Run the Development Server​

Start the lightweight development server to see your changes:

python manage.py runserver

Visit http://127.0.0.1:8000/polls/ in your browser. You should see "Hello, world. You're at the polls index."

Configuration​

Django configuration is handled in the mysite/settings.py file. Key settings include:

  • DATABASES: Configuration for your database (defaults to SQLite).
  • INSTALLED_APPS: A list of strings designating all applications that are enabled in this Django instance.
  • DEBUG: A boolean that turns on/off debug mode. Set to False in production.
  • ALLOWED_HOSTS: A list of strings representing the host/domain names that this Django site can serve.

Verify Installation​

To verify that Django is installed correctly and check its version, run:

python -m django --version

If you are contributing to Django itself, you can run the internal test suite:

cd tests
python -m pip install -r requirements/py3.txt
./runtests.py

Next Steps​

  • Database Setup: Run python manage.py migrate to create the initial database tables for the built-in apps.
  • Admin Interface: Create a superuser with python manage.py createsuperuser to access the automatic Admin Interface at /admin/.
  • Models: Define your data structure in polls/models.py using the Models and Databases.
  • Templates: Learn how to use the Templates and Static Files to separate design from Python code.