When a client sends an HTTP request to a Django application, the framework must determine which code to execute. This mapping between URL patterns and Python view functions is handled by the URL dispatcher, configured primarily in urls.py files.

Basic URL Configuration

In a newly created Django project, the root URL configuration resides in the project's directory. This file contains a Python list named urlpatterns. Django scans this list sequentially to find a matching pattern for the requested URL.

A simple configuration maps a specific path to a view function. For instance, mapping a path to a dashboard view:

from django.contrib import admin
from django.urls import path
from myapp import views

urlpatterns = [
    path("admin/", admin.site.urls),
    path("dashboard/", views.dashboard_view),
]

The corresponding view function receives the request object and returns a response:

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

def dashboard_view(request):
    return HttpResponse("Welcome to the main dashboard.")

Django's design philosophy enforces a strict trailing slash convention. If a user requests /dashboard (without a slash) but the pattern is defined as "dashboard/", Django's middleware will automatically redirect the user to /dashboard/, provided APPEND_SLASH is set to its default True value.

Dynamic Routing with Path Converters

Static routing is insufficient for applications that handle dynamic data. Django provides path converters to capture variable parts of a URL. These are defined using angle brackets.

For example, to retrieve a specific record using an integer identifier:

from django.urls import path
from myapp.views import record_detail

urlpatterns = [
    path("records/<int:record_id>/", record_detail),
]

The view function must accept this captured value as an argument:

# myapp/views.py
def record_detail(request, record_id):
    return HttpResponse(f"Viewing details for record ID: {record_id}")

Built-in converters include str (default), int, slug, uuid, and path. Multiple converters can be chained to capture complex URL structures, such as dates:

path("archive/<int:year>/<int:month>/<int:day>/", views.archive_view)

Regular Expression Routing

For scenarios requiring granular control over URL pattern matching, such as validating a year format or matching specific string patterns, Django offers re_path. This utilizes Python's regular expression syntax.

To enforce a four-digit year constraint:

from django.urls import re_path
from myapp.views import annual_report

urlpatterns = [
    re_path(r"^reports/(?P<year>[0-9]{4})/$", annual_report),
]

In this syntax, (?P<name>pattern) captures the matched string and passes it as a named argument to the view. It is critical to note that parameters captured via re_path are passed as strings, even if the pattern consists solely of digits. Type conversion must be handled inside the view function.

Modularizing URLs with Include

As applications grow, maintaining a single urls.py becomes unmanageable. Django promotes a modular architecture by allowing each app to define its own URL configuration. The root project configuration then includes these app-specific routes using the include() function.

First, define the URLs within the app:

# myapp/urls.py
from django.urls import path
from . import views

app_name = "myapp"

urlpatterns = [
    path("list/", views.list_items, name="list"),
    path("detail/<int:item_id>/", views.item_detail, name="detail"),
]

Then, connect the app URLs to the project root:

# project/urls.py
from django.urls import path, include

urlpatterns = [
    path("myapp/", include("myapp.urls")),
]

This setup routes any request starting with /myapp/ to the urls.py file located inside the myapp directory. This decoupling allows for reusable apps and cleaner project structure.