Getting started

This page covers cloning the framework repository, installing it for development, running its test suite, and building the docs. If you only want to use Django to build an application, install the published package with pip install Django and follow the official tutorial instead.

Prerequisites

• Python ≥ 3.12 (declared in pyproject.toml requires-python)
• A C toolchain only if you want to test against PostgreSQL/MySQL/Oracle backends with their native drivers. SQLite tests run with the stdlib only.
• git, make, and a Unix-like shell (Linux/macOS). Windows works but is less commonly used by core contributors.

Optional:

• PostgreSQL, MySQL/MariaDB, or Oracle for backend-specific tests.
• GDAL/GEOS/PROJ for django.contrib.gis tests.
• tox if you want to run the matrix of supported environments.

Clone and install

git clone https://github.com/django/django.git
cd django
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pip install -r tests/requirements/py3.txt

pip install -e . installs Django in editable mode so that edits to the source tree take effect immediately. The -e . install also exposes the django-admin console script (entry point declared in pyproject.toml as django.core.management:execute_from_command_line).

Run the test suite

The test runner is invoked from the tests/ directory:

cd tests
python runtests.py

runtests.py is a thin wrapper around django.test.utils that discovers test apps in tests/, configures a settings module from tests/test_sqlite.py (the default), and dispatches to django.test.runner.DiscoverRunner. To run a subset:

python runtests.py model_fields
python runtests.py model_fields.tests.IntegerFieldTests
python runtests.py model_fields --parallel 4 --verbosity 2

To run against a different backend, copy a settings template and point --settings at it:

python runtests.py --settings test_postgres -k IntegerField

Sample DATABASES dictionaries for PostgreSQL, MySQL, and Oracle live in docs/internals/contributing/writing-code/unit-tests.txt.

Use tox

tox.ini declares environments for the test suite, formatters, linters, and the docs build:

tox -e py3            # full test suite on the current Python
tox -e black          # black --check
tox -e flake8         # flake8 lint
tox -e isort          # isort --check-only
tox -e docs           # Sphinx HTML build
tox -e lint-docs      # docs prose linter
tox -e zizmor         # workflow lint for .github/workflows/

The [testenv] section sets changedir = tests and runs runtests.py with whatever positional arguments you pass (tox -- model_fields --parallel 4).

Build the docs

The docs are reStructuredText under docs/, built with Sphinx:

cd docs
python -m pip install -r requirements.txt
make html
open _build/html/index.html

docs/_ext/ and docs/_theme/ contain custom Sphinx extensions and the djangodocs theme. The lint.py script runs a prose linter (also exposed as tox -e lint-docs).

Pre-commit hooks

.pre-commit-config.yaml configures black, isort, flake8, pyupgrade, eslint (for js_tests/), and a few custom checks. To install:

python -m pip install pre-commit
pre-commit install

After that every git commit runs the hooks; you can also run pre-commit run --all-files ad-hoc.

Run the development server (smoke test)

The fastest way to make sure your editable install works is to start a project against an in-memory SQLite database:

django-admin startproject mysite /tmp/mysite
cd /tmp/mysite
python manage.py migrate
python manage.py runserver

runserver is implemented in django/core/management/commands/runserver.py. It relies on django.utils.autoreload for the file-watcher loop.

Where to go next

• How to contribute — Trac tickets, pull request process, review expectations.
• Testing — fixtures, the test client, isolating database state.
• Debugging — pdb, the runserver reloader, and reading tracebacks.
• Architecture — the high-level component map, request lifecycle, and ORM data flow.