An app for generic breadcrumbs in Django (>= 1.4).

The idea is to make breadcrumbs out of parts of an url path. This application assumes that your url patterns are well structured. For example like this:

/                                               # root path
/application/                                   # root of an app/module
/application/object_type/                       # list of specific objects
/application/object_type/some_object/           # details of specific object
/application/object_type/some_object/edit/      # edit (or any other operations) of a specific object


  1. Install the package from PyPi. For example via pip:

    pip install django-url-breadcrumbs
  2. Add urlbreadcrumbs to INSTALLED_APPS:

  3. Make sure you have a request context processor django.core.context_processors.request in your TEMPLATE_CONTEXT_PROCESSORS.


Let's assume you have your urls in a form:


from django.conf.urls import patterns, include, url
from myproject.views import some_view

urlpatterns = patterns('',
    url(r'^$', some_view, {'template' : 'index.html'}, name='index'),
    url(r'^test1/', include('test1.urls')),
) in application called test1:

from django.conf.urls import patterns, include, url
from test1.views import some_view

urlpatterns = patterns('',
    url(r'^example/$', some_view, {'template' : 't1.html'}, name='t1home'),

In order to define your breadcrumbs you can make a mapping in like this:

    'index'  : 'Home page',
    't1home' : 'Index page of Test1',

Then somwhere in your base template (lets call it base.html) you can write this:

{% load urlbreadcrumbs_tags %}
{% render_breadcrumbs %}

or you can specify your own template:

{% render_breadcrumbs "test1/mybreadcrumbs_template.html" %}

Also you can just include your breadcrumbs template:

{% include "test1/mybreadcrumbs_template.html" %}

But to use it like this make sure you've added a context procesor urlbreadcrumbs.context_processors.build_breadcrumbs in your TEMPLATE_CONTEXT_PROCESSORS setting.

In your template you have one additional context variable called breadcrumbs which is a list of two-tuples containing name and url of a breadcrumb. The default template used by django-url-breadcrumbs (urlbreadcrumbs/default.html) looks like this:

{% for n,u in breadcrumbs %}
    {% if not forloop.last %}
        <a href="{{ u }}">{{ n }}</a> &raquo;
    {% else %}
        {{ n }}
    {% endif %}
{% endfor %}

So now, assuming template t1.html is extending base.html, when viewing /test1/example/ you should see something like this Home page » Index page of Test1.

Another way of specyfing a name for a breadcrumb is to use a custom url function in your Instead of defining a mapping in URLBREADCRUMBS_NAME_MAPPING setting you can do this in of your ROOT_URLCONF and test1 application:

from django.conf.urls import patterns, include, url
from urlbreadcrumbs import url as burl

urlpatterns = patterns('',
    burl(r'^test1/', include(test1_urls)),


from django.conf.urls import patterns, include, url
from test1.views import some_view
from urlbreadcrumbs import url as burl

urlpatterns = patterns('',
    burl(r'^example/$', some_view, {'template' : 't1.html'}, name='t1home', verbose_name='Index page of Test1'),

This should work as in previous example.

Context aware breadcrumbs

If you want you can provide simple template strings in your mappings. This only works if you render your breadcrumbs with a templatetag (render_breadcrumbs). For example to have some attribute of your object as a part of your breadcrumb you can provide something like this:

    'namespace:edit': 'Edit object {{ }}',

And assuming your view that uses this breadcrumb will provide object in it's context and for example is 'foo' then you should see rendered breadcrumb as Edit object foo.

One important prerequisite for this to work properly is that every view "below" the url namespace:edit MUST provide object in it's context. By "below" we mean every url that starts with the same url that namespace:edit is configured to.

Demo project

To run a demo project that is using django-url-breadcrumbs try this:

pip install Django
export DJANGO_SETTINGS_MODULE=urlbreadcrumbs.tests.settings runserver

and then visit in your browser.

You can find source code of this demo project in urlbreadcrumbs/tests.


Ideas and/or bug reports are welcome. Consider reporting an issue on

Pull requests are also welcome ;).

To start working on this app get the source from Bitbucket:

hg clone

and in a newly created virtualenv do this:

pip install -r dev_requirements.txt
python test


django-url-breadcrumbs uses pytest for running it's test suite and tox for checking it's compatibilty with different Python and Django versions.

In order to perform tests with your current python and django installation do this:

python test

To test it with different python and django versions run this: