url-dispatcher

The URL Dispatcher is Django’s routing mechanism that maps incoming HTTP request paths to view functions or class-based views using a declarative URL configuration (URLconf) composed of path() and re_path() patterns with optional converters, namespaces, and included sub-URLconfs.

The URL dispatcher solves the problem of connecting human-readable URLs to application logic. Instead of hardcoding URL-to-view mappings in a single file, Django uses a modular, hierarchical system where each app defines its own URL patterns, which are then included in the project’s root URLconf. This enables namespacing, reversal, and maintainable routing at scale.

1. Request received — HTTP request path extracted from WSGI/ASGI environ
2. Root URLconf loaded — ROOT_URLCONF setting points to project’s urls.py
3. Pattern matching — Iterator through urlpatterns list in order; first match wins
4. Converter extraction — Path converters (int, str, slug, uuid, path) parse and type-cast URL segments
5. View resolution — Matched view callable receives request + extracted kwargs
6. Namespace resolution — include() with namespace enables reversible named URLs across apps

• Order matters: Patterns evaluated top-to-bottom; first match wins
• Converters: Built-in (int, str, slug, uuid, path) + custom converters via register_converter()
• Reversal: reverse('name', args=[...]) and {% url 'name' %} generate URLs from names
• Namespaces: app_name + include(namespace=...) prevent name collisions across apps
• Lazy evaluation: include() accepts string to avoid circular imports

• Built from: Django Web Framework — Core routing component
• Built from: HTTP Protocol — Routes HTTP request paths
• Builds into: Function-Based Views — Targets for URL patterns
• Builds into: Class-Based Views — as_view() as URL target
• Builds into: URL Reversal — Named patterns enable reversal
• Contrasts with: Flask @route — Decorator-based, single-file routing
• Contrasts with: FastAPI Path Operations — Type-annotated, automatic OpenAPI
• Related: DRF Routers — Auto-generates URL patterns for ViewSets

• Trailing slashes: APPEND_SLASH redirects but can cause POST data loss; be consistent
• Catch-all patterns: path('<path:resource>/', ...) at end prevents 404s but hides bugs
• Namespace collisions: Missing app_name in included URLconf breaks reversal
• Converter precedence: More specific patterns must come before general ones (<int:pk> before <str:slug>)