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: OS Independent (Linux, macOS, Windows).
• Dependencies: Django requires asgiref and sqlparse. On Windows, tzdata is also required.

Installation

The recommended way to install Django from source is using pip:

# From the root of the repository
python -m pip install .

Optional Dependencies

For enhanced security features, you can install optional password hashing support:

• Argon2: pip install "Django[argon2]"
• Bcrypt: pip install "Django[bcrypt]"

Hello World / Quick Start

Follow these steps to create a minimal Django project and run the development server.

1. Create a Project

Use the django-admin CLI to bootstrap a new project:

django-admin startproject mysite
cd mysite

2. Create a View

Create a new file mysite/views.py with a simple "Hello World" function:

# mysite/views.py
from django.http import HttpResponse

def hello(request):
    return HttpResponse("Hello, world! Django is running.")

3. Configure URLs

Map a URL to your new view in mysite/urls.py:

# mysite/urls.py
from django.contrib import admin
from django.urls import path
from .views import hello

urlpatterns = [
    path('admin/', admin.site.urls),
    path('hello/', hello),
]

4. Run the Server

Start the development server:

python manage.py runserver

Visit http://127.0.0.1:8000/hello/ in your browser to see the result.

Verify Installation

To confirm Django is installed correctly and check the version:

python -m django --version

Running the Test Suite

If you are contributing to Django or want to verify the codebase itself, you can run the internal tests:

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

Next Steps

• Tutorial: Follow the official Writing your first Django app tutorial to build a poll application.
• Models: Learn how to define your data models in the Models and Databases.
• Admin: Explore the automatic Getting Started with the Admin for managing your content.
• Settings: Configure your project using the Project Settings Architecture.

Troubleshooting

• ImportError: If you see ImportError: No module named django, ensure your virtual environment is activated and you ran the installation command.
• Port in Use: If runserver fails because a port is already in use, you can specify a different port: python manage.py runserver 8080.
• Database Migrations: If you see warnings about unapplied migrations, run python manage.py migrate to initialize the default database tables.