Organizing URLs by Including urls.py from Multiple Apps Using the include() Function

When developing Django projects, it is common to have multiple apps, each with its own set of views and functionality. As projects grow, managing all URL patterns in a single urls.py file becomes cumbersome and error-prone. To maintain a clean and scalable project structure, Django provides the include() function, which allows you to organize URLs at the app level and include them in the project’s main URL configuration.

This guide explains how to effectively include URLs from multiple apps, organize URL patterns, and follow best practices for maintainable Django projects.

Understanding Django URL Routing

Django uses a URL dispatcher to map URLs to views. The URL dispatcher examines the request URL and selects the appropriate view to handle it.

• URL patterns are defined in urls.py using the path() or re_path() functions.
• Each URL pattern can point to a view function, class-based view, or another URL configuration.

Example of a simple URL pattern in a project-level urls.py:

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

urlpatterns = [
path('admin/', admin.site.urls),
path('', views.home, name='home'),
]

For small projects, defining all URLs here may work. But as projects grow, this becomes unmanageable.

---

The include() Function

What is include()?

The include() function allows you to reference another URL configuration instead of writing all URL patterns in the main urls.py. This is particularly useful when each app has its own urls.py file.

• include() helps separate concerns.
• Each app manages its own URLs independently.
• The main urls.py file acts as a router to delegate URL handling to apps.

---

Basic Syntax of include()

from django.urls import path, include

urlpatterns = [
path('blog/', include('blog.urls')),
]

Here:

• All URLs defined in blog/urls.py are prefixed with blog/.
• This makes it easy to organize multiple apps like blog, shop, or accounts.

---

Organizing URLs by App

1. Create urls.py in Each App

Each Django app should have its own urls.py file. Example for a blog app:

blog/urls.py

from django.urls import path
from . import views

urlpatterns = [
path('', views.index, name='blog_index'),
path('post/<int:post_id>/', views.post_detail, name='post_detail'),
]

• The empty string '' matches /blog/.
• Dynamic URL patterns like <int:post_id> pass arguments to views.

---

2. Include App URLs in Project urls.py

project/urls.py

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

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

Now, the URL /blog/ calls blog.views.index, and /blog/post/1/ calls blog.views.post_detail with post_id=1.

---

Advantages of Using include()

1. Scalability: Each app manages its own URLs.
2. Maintainability: Avoid a massive urls.py in the project directory.
3. Reusability: Apps can be reused in different projects by including their URLs.
4. Namespace Support: Prevents name collisions using app namespaces.

---

Using Namespaces for URLs

Namespaces allow you to differentiate URLs across apps with the same view names.

1. Define an app_name in App URLs

blog/urls.py

app_name = 'blog'

urlpatterns = [
path('', views.index, name='index'),
path('post/<int:post_id>/', views.post_detail, name='post_detail'),
]

2. Include URLs with a Namespace

project/urls.py

path('blog/', include('blog.urls', namespace='blog')),

3. Use Namespaced URL in Templates

<a href="{% url 'blog:post_detail' post.id %}">Read more</a>

This avoids conflicts if multiple apps have a post_detail view.

---

Using Dynamic URL Patterns

Dynamic URLs allow you to capture variables from the URL and pass them to views.

Example in shop/urls.py:

from django.urls import path
from . import views

app_name = 'shop'

urlpatterns = [
path('', views.product_list, name='product_list'),
path('product/<int:product_id>/', views.product_detail, name='product_detail'),
path('category/<slug:category_slug>/', views.category_view, name='category_view'),
]

• <int:product_id> passes an integer.
• <slug:category_slug> passes a slug string.

---

Including Multiple Apps

For larger projects, multiple apps can be included in the main urls.py:

urlpatterns = [
path('admin/', admin.site.urls),
path('blog/', include('blog.urls', namespace='blog')),
path('shop/', include('shop.urls', namespace='shop')),
path('accounts/', include('accounts.urls', namespace='accounts')),
]

• Each app manages its own URL patterns independently.
• The project-level urls.py only delegates requests.

---

Nested Includes

Django allows nested includes, meaning an app can include another URLconf.

accounts/urls.py

from django.urls import path, include

urlpatterns = [
path('login/', views.login_view, name='login'),
path('profile/', include('profile.urls', namespace='profile')),
]

• Requests to /accounts/profile/ are delegated to profile.urls.
• Nested includes help in modular design.

---

Best Practices for URL Organization

1. Create a urls.py in Each App
   Each app should manage its own URLs for clarity.
2. Use Namespaces
   Avoid conflicts by specifying app_name in app URLs.
3. Use Clear URL Patterns
   Follow readable and RESTful conventions, e.g., /blog/post/<int:id>/.
4. Group Related URLs
   Keep logically related URLs together in one urls.py.
5. Use Include Instead of Hardcoding
   Delegate app URLs to maintain a clean project urls.py.
6. Document Your URLs
   Keep comments and docstrings to help developers understand URL structures.

---

Handling URL Parameters

Django allows multiple types of converters for URL parameters:

• int: Matches integers
• str: Matches non-empty strings excluding slashes
• slug: Matches letters, numbers, hyphens, and underscores
• uuid: Matches UUID strings
• path: Matches any string, including slashes

Example:

path('order/<uuid:order_id>/', views.order_detail, name='order_detail')

• Captures order_id as a UUID and passes it to the view.

---

Reverse URL Resolution

Django allows reverse URL resolution to generate URLs dynamically.

Example in templates:

<a href="{% url 'blog:post_detail' post.id %}">Read Post</a>

Example in views:

from django.urls import reverse
from django.shortcuts import redirect

def redirect_to_post(request, post_id):
url = reverse('blog:post_detail', args=[post_id])
return redirect(url)

• Using reverse() or {% url %} avoids hardcoding URLs.

---

Handling 404s with Includes

When using include(), Django still raises Http404 if no matching pattern is found.

• Ensure the app-level urls.py handles all necessary routes.
• Use a project-level catch-all pattern for custom 404 pages:

handler404 = 'myapp.views.custom_404_view'

---

Example Project Structure

project/
├── project/
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── blog/
│   ├── views.py
│   ├── urls.py
│   └── templates/blog/
├── shop/
│   ├── views.py
│   ├── urls.py
│   └── templates/shop/
├── accounts/
│   ├── views.py
│   ├── urls.py
│   └── templates/accounts/

• Each app has its own urls.py.
• Project urls.py uses include() to route requests to apps.
• Templates remain organized by app.

---

Using re_path() for Complex Patterns

re_path() allows regular expressions in URLs for more control:

from django.urls import re_path

urlpatterns = [
re_path(r'^archive/(?P<year>[0-9]{4})/$', views.archive, name='archive'),
]

• Captures 4-digit year from the URL.
• Useful for legacy patterns or complex routing needs.

---

Advantages of Modular URL Design

1. Easier Maintenance
   Changes in one app’s URLs do not affect other apps.
2. Improved Readability
   Developers can locate URL patterns quickly.
3. Reusability
   Apps can be reused across projects with minimal changes.
4. Clear Namespace Management
   Avoids name collisions in templates and views.
5. Better Testing
   Individual app URLs can be tested independently.

---

Best Practices Summary

• Always use include() for app-level URLs.
• Assign app_name for each app to enable namespaces.
• Use readable and consistent URL patterns.
• Keep dynamic parameters simple and predictable.
• Organize nested URLs logically if apps have multiple submodules.
• Test URL resolution with reverse() to ensure reliability.

---

Real-World Example

blog/urls.py

from django.urls import path
from . import views

app_name = 'blog'

urlpatterns = [
path('', views.index, name='index'),
path('post/<int:post_id>/', views.post_detail, name='post_detail'),
]

shop/urls.py

from django.urls import path
from . import views

app_name = 'shop'

urlpatterns = [
path('', views.product_list, name='product_list'),
path('product/<int:product_id>/', views.product_detail, name='product_detail'),
]

project/urls.py

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

urlpatterns = [
path('admin/', admin.site.urls),
path('blog/', include('blog.urls', namespace='blog')),
path('shop/', include('shop.urls', namespace='shop')),
]

• /blog/ → blog.index
• /blog/post/1/ → blog.post_detail(post_id=1)
• /shop/ → shop.product_list
• /shop/product/5/ → shop.product_detail(product_id=5)