How to include app URLs to project URLs in Django

If you create a Django app using the startapp command, you’ll notice that the app folder created does not include the urls.py file. This does not mean that we have put all the routes of our Django website in the urls.py of our project folder. If we had to do that, our project would be messy and hard to manage and scale. The best solution to that is to create the urls.py manually for each app in our project, then include that file in the project’s urls.py file. This post will show you how to include URLs to main URLs in Django.

This post assumes that you’ve already created a Django project. We will start by creating the app, then we’ll create the urls.py file for the app, and then we’ll include the file in the main URLs of our Django project. If you have an app already, you can start at the second section where we register the app.

Django Include URLs: Table of Contents

Steps to follow to include app URLs to project URLs in Django:

  1. Create A Django App.
  2. Register the App to Settings.py
  3. Create A urls.py file for the app
  4. Link the urls.py in the project’s urls.py
  5. Add URL patterns to the App’s urls.py

Let’s do this step by step.

1. Create A Django App.

You can create a Django app using the startapp command. Type the following code in the terminal of your project. Make sure the virtual environment is activated if you’re using one.

(env) $ python manage.py startapp blog

In this case, blog is the name of the app. It can be any name, just make sure it resonates with what the app is about. The structure of a newly created app looks like this:

[project_name]
β”œβ”€β”€ config
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ settings.py
β”‚   β”œβ”€β”€ urls.py
β”‚   └── wsgi.py
β”œβ”€β”€ blog # new app
|   β”œβ”€β”€ migrations
β”‚   β”œβ”€β”€ _init_.py
β”‚   β”œβ”€β”€ admin.py
β”‚   β”œβ”€β”€ apps.py
β”‚   β”œβ”€β”€ models.py
|   β”œβ”€β”€ views.py
|   └── tests.py  
└── manage.py

As you can see, there is no urls.py file like there is in the config folder (the project folder). Therefore, we have to create it manually. But before we do so, we have to register the new app to Django’s settings.py so that its URLs can be recognized as part of the project.

2. Register the App to Settings.py

In the settings.py file of your project folder, in the INSTALLED_APPS list, add the string name of your app.

# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

     # My apps
    'blog' #new
]

3. Create A urls.py file for the app

Next, create the urls.py file in the app folder.

...
β”œβ”€β”€ app_name # new app
β”‚   β”œβ”€β”€ _init_.py
β”‚   β”œβ”€β”€ admin.py
β”‚   β”œβ”€β”€ apps.py
β”‚   β”œβ”€β”€ models.py
|   β”œβ”€β”€ views.py
|   β”œβ”€β”€ urls.py # new file
|   └── tests.py  
...

The name of the file can be anything for sure, but it’s a best practice to call it urls.py because of its role in the Django app. Now that the file is there, we have to link it to the project’s URLs.

4. Include the urls.py in the project’s urls.py

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

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

We first import the include() function which according to Django is ‘A function that takes a full Python import path to another URLconf module that should be β€œincluded” in this place.’

Next, we add a URL pattern and pass in a route and the include() function. The route is an empty string to indicate the home page, meaning all other routes that are imported to this pattern are going to start from the home page.

We could have done it like this:

...
path('blog/', include('blog.urls')) #new
...

This means that all URL routes from the blog app are going to start with the blog/ part followed by anything you specify in the app urls.py itself.

Next, we pass in the include() function as the second argument and we pass to it the URLs of our app in the form 'app.urls'. It has to be a string.

If you forget how to include app URLs to project URLs, Django has added some helpful comments right above the code in the urls.py file of your project. You can always check them for reference.

"""config URL Configuration

The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/4.0/topics/http/urls/
Examples:
Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""
...

In this case, the part you’re looking for is under the Including another URLconf section.

5. Add URL patterns to the App’s urls.py

Finally, let’s test our Django application and see if we have linked the URLs correctly to each other. In the urls.py of your app, add the following code:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.index, name = 'home')
]

In the views.py of the app folder, add the following code.

from django.shortcuts import render
from django.http import HttpResponse #new

def index(request): #new
    return HttpResponse('<h1>Django Include URLs</h1>')

This is a simple view that returns an HTML heading which says Django Include URLs. If you run the Django server and navigate to 127.0.0.1:8000. You should see something like this:

Conclusion

Okay, that was all for this Django include URLs tutorial. If you have any questions, feel free to let me know in the comments section below.

Stephen Mclin
Stephen Mclin

Hey, I'm Steve; I write about Python and Django as if I'm teaching myself. CodingGear is sort of like my learning notes, but for all of us. Hope you'll love the content!

Articles: 125